Bidding Android iOS Unity JS API Media API 常见问题

优量汇Server Bidding接口文档

版本 日期 内容 最低支持SDK版本
1.0 21/08/09 优量汇Server Bidding初版协议 iOS:4.13.0;
Android:4.390.1260
1.1 21/08/18 修改文档中connecttion_type类型为integer; 新增ifa,竞胜/竞败上报宏替换说明 iOS:4.13.0
Android:4.390.1260
1.2 21/09/02 修改竞败上报相关说明;新增屏蔽请求底价功能说明;新增设备ext对象校验说明; iOS:4.13.0
Android:4.390.1260
1.3 21/09/07 增加竞价回包返回和使用token拉取广告回包时间间隔限制补充说明 iOS:4.13.0
Android:4.390.1260
1.4 21/09/22 增加video对象必填场景的说明 iOS:4.13.0
Android:4.390.1260
1.5 21/09/26 1.修改devicetype字段类型为integer(历史字符串保持兼容)。
2.底价字段bidfloor、bidfloorcur改为非必填,后台底价功能已屏蔽。
iOS:4.13.0
Android:4.390.1260
1.6 21/10/26 增加调试工具使用说明 iOS:4.13.0
Android:4.390.1260
1.7 21/11/19 增加SDKInfo获取能力说明,用于优量汇SDK版本新增功能支持信息获取 iOS:4.13.30
Android:4.430.1300
1.8 21/12/20 增加竞败上报时竞胜方来源的枚举值 iOS:4.13.30
Android:4.430.1300

1 交互流程

1.1 广告请求和返回流程

STEP1:流量方 App 调用优量汇SDK 接口获取请求 buyerId 和SDKInfo(其中SDKInfo可选)用于从优量汇后端获取竞价信息
STEP2:流量方ADX携带 buyerId和SDKInfo(其中SDKInfo可选) 信息请求优量汇后台
STEP3:优量汇后台返回流量方adx竞价回包,其中包含竞价信息和sdk渲染广告的token
STEP4:流量方ADX完成比价后,上传竞价成功/失败及扣费等信息给优量汇后台服务
STEP5:流量方APP使用竞价回包中的token调用优量汇SDK展示广告接口
STEP6:流量方APP调用优量汇SDK曝光上报接口回传竞胜价格

备注:

(1) STEP4和STEP5无严格顺序,且竞价失败后不需要进行STEP5和6;
(2) STEP3开发者收到竞价回包与STEP5使用token拉取广告回包的时延不可超过90s,否则可能无法拉取广告回包;
(3) STEP1和STEP2中 获取和携带SDKInfo信息为可选操作,用于优量汇SDK各版本新增功能支持信息补充,建议开发者获取并上传,可及时支持SDK后续迭代版本功能,提升变现效果。

2 接口协议

2.1 调用YLH SDK获取竞价请求buyerID和SDKInfo

2.2 Server端竞价请求协议

2.2.1 竞价请求

采用OpenRTB协议

字段 类型 必填 描述
id 字符串 流量方ADX生成的出价请求 ID;例如,'570b0eb14e67c98f761a0ca0'。
imp 对象数组 请参阅Imp对象。
app 对象 请参阅应用程序对象。
device 对象 请参阅设备对象。
cur 字符串数组 以ISO-4217-alpha 显示的允许的拍卖货币,每次请求仅选择支持一种货币,目前仅支持CNY,例如,["CNY"],单次请求。
ext 对象 请求BuyerId以及其他功能支持开关
字段 类型 必填 描述
id 字符串 流量方ADX生成的展示 ID;例如,'3a06eb14e67c98f761add01'。
bidfloor 浮动 让出价合格的最低出价价格;例如,'8.72',精度为小数点后两位,单位(分/千次);目前已屏蔽底价功能
bidfloorcur 字符串 以 ISO-4217-alpha 显示的展示货币;目前仅支持CNY,例如,'CNY'。
video 对象 可选 请参阅视频对象,召回视频素材时必填,建议填写,提升变现效率。
tagid 字符串 广告位 ID;
字段 类型 必填 描述
h integer 视频高度,可能影响展示效果
w integer 视频宽度,可能影响展示效果
minduration integer 视频必须播放的最少秒数。
maxduration integer 视频可以播放的最长秒数。
字段 类型 必填 描述
id 字符串 优量汇的appid;例如,'3709293'。
bundle 字符串 捆绑包或包名称(例如,'com.supercell.hayday')
name 字符串 应用程序名称;例如,'hay day'。
字段 类型 必填 描述
ua 字符串 设备浏览器用户代理字符串;例如,'Mozilla/5.0 (iPhone; CPU iPhone OS 9_1 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13B143 Safari/601.1'。
ip 字符串 当ipv6存在时,非必须
展示的IP地址,例如: '212.14.27.104'。
ipv6 字符串 当IP地址存在时,该字段非必须
展示的IPv6地址,示例:'3ffe:1900:4545:3:200:f8ff:fe21:67cf'。
h integer 以像素计的设备屏幕高度。
w integer 以像素计的设备屏幕宽度。
connectiontype integer 请参阅 OpenRTB 2.6 第 5.22 部分。
ifa 字符串 支持的供广告客户用于纯文本的 ID,安卓系统为imei,ios系统为idfa;例如,'e4fe9bdecaa047b6908dffba3fa184f2'。
didmd5 字符串 imei信息的MD5值,用以补充无法传明文imei的请求。取值方法:调用的系统 API 为 TelephonyManager#getDeviceId,该 API 返回的可能是 IMEI(GSM 设备,纯数字),也可能是 MEID(CDMA 设备,可能有字母)。需要将imei 信息转化为小写,并对其结果计算MD5值,且确保其最终结果为小写。
geo 对象 请参阅地理对象。
make 字符串 设备制造。
model 字符串 设备型号。
os 字符串 设备操作系统;例如,'iOS', 'Android'。枚举值:
- 'iOS'
- 'Android'
- 'Windows'
osv 字符串 设备操作系统的版本;例如,'9.1', '8.0'。
devicetype integer 请参阅 OpenRTB 2.5 第5.21部分
language 字符串 以 ISO-639-1-alpha-2 显示的设备语言;例如,'en'。
ext 字符串 请参阅设备ext对象
字段 类型 必填 描述
oaid 字符串 安卓oaid,能获取到则上传,可能影响广告效果
android_id 字符串 安卓id,能获取到则上传,可能影响广告效果
time_zone 字符串 在 IANA 时区数据库中使用时区名称作为格式的设备时区设置;例如,'America/Los_Angeles'。
字段 类型 必填 描述
country 字符串 以 ISO-3166-1-alpha-3 显示的国家/地区代码;例如,'USA'。
lat 浮动 设备的纬度;例如,'[-90, 90]'。
long 浮动 设备的经度;例如,'[-180, 180]'。
字段 类型 必填 描述
buyer_id 字符串 优量汇SDK获取的buyerID
wx_installed boolean 是否安装微信,用于判断是否能支持微信小程序广告
opensdk_ver string openSDK 版本,用于判断是否能支持微信小程序广告
support_h265 boolean 是否支持h265
support_splash_zoomout boolean 是否支持开屏 V+
sdk_info string 优量汇SDK获取的SDKInfo

2.2.2 竞价响应

字段 类型 必填 描述
id 字符串 BidRequest ID是由请求生成的,示例 '570ffeb14e67998f761a791c'。这必须与 BidRequest object 的ID匹配。
bidid 字符串 帮助记录/跟踪的出价人生成的唯一响应 ID
cur 字符串 使用 ISO-4217 alpha 代码的出价货币,目前支持CNY
seatbid 对象数组 seatbid 对象数组;如果进行了出价则需要。
nbr integer 未参与竞价的原因,详见错误码含义
token 字符串 优量汇有广告参与竞价时必填,为返回展示广告的token,竞价成功后调用优量汇SDK展示广告时使用
字段 类型 必填 描述
seat 字符串 Bidder seat ID是该代表该竞价请求来源。请参阅 OpenRTB 2.5
bid 对象数组 请查看Bid object。 至少拥有一个竞价
字段 类型 必填 描述
id 字符串 traceid。
impid 字符串 与为其出价的出价请求的展示有关的展示 ID。必须与出价请求中imp对象中的 ID 相同。
price 浮动 以 CPM 单位表示的出价价格;例如,'10.30'。单位:分/千次,精度为小数点后两位
nurl 字符串 竞价胜出时 调用的胜出通知 URL。
lurl 字符串 竞价失败时,调用的通知URL。
cid 字符串 建议 广告 ID。
crid 字符串 建议 创意 ID。
bundle 字符串 建议 唯一的市场 ID,这是平台特定的应用程序识别码,对于应用是唯一的。
- 在 Android 上,这应该是捆绑包或包名称(例如,'com.supercell.hayday')。
- 在 iOS 上,这是一个数字 ID。
h integer 建议 创意的高度。
w integer 建议 创意的宽度。
字段 类型 必填 描述 备注
img 字符串 素材url (视频广告为封面图或者背景图url) 非必需,仅白名单开发者适用
video 字符串 视频素材url 非必需,仅白名单开发者适用
landing_page 字符串 落地页地址 非必需,仅白名单开发者适用
title 字符串 标题 非必需,仅白名单开发者适用
app_name 字符串 应用名称 非必需,仅白名单开发者适用
package_name 字符串 应用包名 非必需,仅白名单开发者适用
advertiser_name 字符串 广告主名称 非必需,仅白名单开发者适用

2.2.3 示例

错误码含义请见:https://developers.adnet.qq.com/backend/error_code.html

我们提供了在线联调测试工具,对于常见问题,会在返回中提示问题原因,并提供改进建议,提高接入效率,平台地址是:https://utest.gdt.qq.com/devtool/#/tool/stos。

平台需要登录,请使用开发者平台账号登录即可。

2.3 调用优量汇SDK展示广告接口

2.4 竞价成功/失败上报

宏替换:替换=后面整体字符串,例如${AUCTION_LOSS}替换为1

"nurl":"https://win.gdt.qq.com/win_notice.fcg?adx_id=6&viewid=&win_price=${AUCTION_PRICE}&server_bidding_type=1&highest_loss_price=${HIGHEST_LOSS_PRICE}"
"lurl":"https://win.gdt.qq.com/win_notice.fcg?adx_id=6&viewid=&win_price=${AUCTION_PRICE}&server_bidding_type=1&win_seat=${AUCTION_SEAT_ID}&loss=${AUCTION_LOSS}"
枚举值 竞胜方来源
1 输给优量汇其它广告位
2 输给第三方ADN且不回传具体渠道时传此值
3 输给自售广告主
枚举值 失败原因
1 竞争力不足
2 竞价回包返回超时,上报接口待开放
3 竞价回包不合法(无广告填充且返回未参竞错误码),上报接口待开放
10001 其他

2.5 曝光上报调用优量汇接口回传竞胜价格

 文档反馈

腾讯公司 版权所有