实时检索对接
更新日志
| 编号 | 日期 | 作者 | 修改内容 |
|---|---|---|---|
| 1 | 2019-08-18 | lihuifeng01 | 整合RTB、信息流PDB&PD、开屏PDB&PD检索bid协议 输出统一对接文档 |
| 2 | 2019-11-05 | lihuifeng01 | 新增oaid字段支持 |
1 介绍
百度原生程序化投放的检索Bid协议，是基于OpenRtb协议实现，用于实时检索过程中，将流量分发给需求方，需求方选择流量以及返回物料数据/选择已有物料进行投放的过程。 Bid Request由百度原生广告检索端发起，需求方接收请求，并分析流量价值和运用投放策略，来决策是否选择流量，将挑量/退量结果返回给百度。
接入方需提供接收请求的http地址，并支持自动地域分流，百度侧作为流量上游，服务器分布在北京、南京、广州三个地域，外部DSP应实现每个地域可最高承载3000qps的负载能力，同时实现平均40ms，每个地域高峰均值不超过60ms的返回时间。
2 接口定义
百度原生品牌程序化实时Bid接口(Bid Request)使用http post方式进行交互，请求消息使用protobuf，访问超时设置为 100ms，Content-Type 设为 application/octet-stream。
2.1 Bid Request
参考通用的OpenRTB规范，Bid Request结构如下图所示：
BidRequest object详细字段及含义
| 字段名称 | 类型 | 描述 | 字段必填 |
|---|---|---|---|
| id | string | 请求ID | 必填(开屏会填充) |
| imp | array of Imp objects | 曝光对象，一次request可以包含多个imp(开屏中一个imp对应一个广告位的请求) | 选填(开屏会填充) |
| app | App object | APP信息 | 选填(开屏会填充) |
| device | Device | 设备信息 | 选填(开屏会填充) |
| at | int32 | 竞价方式, PDB&PD为定价, 此字段不传, RTB当前只支持二价 | 选填(开屏未使用) |
| tmax | int32 | 超时时间 | 选填(开屏未使用) |
| ext | string | 百度与接入方约定的定制化信息 | 选填(开屏未使用) |
| trans_info_list | array of GeneralTransInfo objects | 特殊字段/附加字段,key-value形式 | 选填(开屏未使用) |
Imp object，开屏广告请求包含Banner对象，信息流包含Native对象:
| 字段名称 | 类型 | 描述 | 字段必填 |
|---|---|---|---|
| id | string | 曝光 ID | 必填(开屏会填充为请求id) |
| tagid | string | 广告位ID,详见《广告位列表》 | 必填(开屏会填充) |
| bidfloor | double | 竞价底价，单位是分/千次曝光，即CPM | 开屏广告未使用，RTB必传 |
| secure | bool | 标识是http还是https,0 = non-secure, 1 = secure | 选填(开屏未使用) |
| campaign_date | string | 预投放日期,如"20160602" | 选填(仅开屏会填充） |
| banner | Banner object | banner类型的广告位 | 选填（仅开屏填充长宽信息） |
| native | Native object | native类型的广告位 | 选填(仅信息流填充) |
| templelist | array of string | 流量支持的模板ID列表,详见《物料规格》 | 选填(开屏未使用) |
| dealidlist | array of string | 订单ID列表(经百度筛选后可选的订单ID列表) | 选填（PDB&PD模式必填，repeated类型，一个Imp中可能包含多个dealid）(开屏会填充) |
| adidlist | array | 该流量可选的adid list | 暂未使用(开屏不使用) |
Banner object详细字段及含义：
| 字段名称 | 类型 | 描述 | 字段必填 |
|---|---|---|---|
| w | int32 | 广告位宽度 | 选填(开屏会填充) |
| h | int32 | 广告位高度 | 选填(开屏会填充) |
| pos | int32 | banner位置 | 选填(开屏未使用) |
Native object详细字段及含义：
| 字段名称 | 类型 | 描述 | 字段必填 |
|---|---|---|---|
| request_native | NativeRequest object | 选填 |
NativeRequest object 详细字段及含义:
| 字段名称 | 类型 | 描述 | 字段必填 |
|---|---|---|---|
| plcmtcnt | int32 | 广告物料的个数（RTB填充） | 选填 |
App object详细字段及含义：
| 字段名称 | 类型 | 描述 | 字段必填 |
|---|---|---|---|
| app_name | string | app name | 选填 |
| ver | string | Application version | 选填(开屏未使用) |
| bundle | string | package name | 选填(开屏未使用) |
| package_name | string | 应用包名, 例如：com.moji.MojiWeather | 选填(开屏会填充) |
| category | array of string | app类目 | 选填(开屏会填充) |
Device object详细字段及含义：
| 字段名称 | 类型 | 描述 | 字段必填 |
|---|---|---|---|
| ua | string | user agent | 选填(开屏会填充) |
| ip | string | IPV4地址 | 选填(开屏会填充) |
| ipv6 | string | IPV6地址 | 选填(开屏未使用) |
| geo | Geo object | 实时位置信息 | 选填(开屏未使用) |
| model | string | device model | 选填(开屏会填充) |
| os | string | 设备平台 ‘ios’/‘android’ | 选填(开屏会填充) |
| osv | string | 操作系统版本 | 选填(开屏会填充) |
| w | int32 | 屏幕宽度 | 选填(开屏未使用) |
| h | int32 | 屏幕高度 | 选填(开屏未使用) |
| connectiontype | ConnectionType | 网络类型 | 选填(开屏会填充) |
| devicetype | DeviceType | 设备类型 | 选填(开屏会填充) |
| idfa | string | iOS设备的IDFA明文（全大写） | 选填(开屏会填充) |
| oaid | string | Android 10以上设备oaid明文 | 选填(开屏会填充) |
| imei_md5 | string | Android设备imei设备号md5加密串（32位大写） | 选填(开屏会填充) |
| android_id | string | Android设备AndroidId | 选填(开屏未使用) |
| caid | string | IOS caid设备号（全小写） | 选填(开屏会使用) |
Geo object详细字段及含义：
| 字段名称 | 类型 | 描述 | 字段必填 |
|---|---|---|---|
| lat | double | 选填 | |
| lon | double | 选填 | |
| type | LocationType | 选填 |
GeneralTransInfo object详细字段及含义:
| 字段名称 | 类型 | 描述 | 字段必填 |
|---|---|---|---|
| key | string | 必填 | |
| value | string | 选填 | |
| value_list | array of Pair objects | 数组形式的内容 | 选填 |
Pair object详细字段及含义:
| 字段名称 | 类型 | 描述 | 字段必填 |
|---|---|---|---|
| key | string | 选填 | |
| value | string | 选填 |
####请求字段示例
{
"id": "1569628278785885030",
"imp": [{
"id": "1569628278785885030",
"banner": {
"w": 1242,
"h": 2208
},
"tagid": "735",
"campaign_date": "20220823",
"dealidlist": ["100338"]
}],
"app": {
"app_name": "百度",
"package_name": "com.baidu.searchbox",
"category": ["101701"]
},
"device": {
"ua": "",
"ip": "1.2.3.4",
"model": "V2049A",
"os": "android",
"osv": "11",
"connectiontype": "CELL_4G",
"devicetype": "APP",
"oaid": "XXXXXXXXXXXXXXXXXXXXXXXXXX",
"operator": 0,
"imei_md5": "XXXXXXXXXXXXXXXXXXXXXXXXXX"
}
}
2.2 Bid Response
竞价结果返回接口以 http post 方式进行返回，消息内容使用 protobuf 进行封装，序列化之后返回。响应的 Content-Type 设为 application/octet-stream。不参与竞价，也必须在超时时限内返回 protobuf。格式的响应，超时或者返回信息无法解析被视为访问失败。 竞价结果返回接口有几种方式：Static、HTML Snippet。其中 Static 方式是最基本的接口，所有的 DSP 都可以采用。HTML Snippet 方式使用必须得到百度的确定，并且采用 HTML Snippet 方式返回的。Bid Response 必须小于 15K。
Bid Response结构如下图所示：
BidResponse object详细字段及含义：
| 字段名称 | 类型 | 描述 | 字段必填 |
|---|---|---|---|
| id | string | 请求ID | 必填(必填，但开屏不使用) |
| bidid | string | 对应的bidder response id,debug string | 选填(开屏未使用) |
| seatbid | array of SeatBid objects | 所有广告信息(开屏中一个seatbid对应一个Imp) | 选填(开屏必填) |
| resmicrotime | string | 下游bid响应发出的时间戳（精确到毫秒） | 选填(开屏未使用) |
SeatBid object详细字段及含义：
| 字段名称 | 类型 | 描述 | 字段必填 |
|---|---|---|---|
| bid | array of Bid objects | 对应到imp | 选填(开屏必填) |
Bid object详细字段及含义：
| 字段名称 | 类型 | 描述 | 字段必填 |
|---|---|---|---|
| id | string | bidder response id | 必填(但开屏未使用) |
| impid | string | 对应的曝光ID | 必填(但开屏未使用) |
| price | float | 出价价格，单位是分/千次曝光，即CPM（PDB&PD模式均为定价投放, 该字段值被忽略） | 必填(但开屏未使用) |
| adid | string | 需求方针对此流量选择下发的广告id（广告id是需求方上传物料时,由百度生成并返回的adid） | 必填(开屏使用，创意id) |
| nurl | string | 竞价成功通知 | 选填(开屏未使用) |
| impurl | array of string | imp notice url | 选填(开屏使用,展现监测链接) |
| expurl | array of string | click notice url | 选填(开屏使用，点击监测链接) |
| adm | string | 广告素材,json序列化的字符串（投放信息流PDB/PD/RTB，如果合作方以先投后审方式接入，则需填充该字段） | 选填(开屏未使用)，该字段数据格式目前以表格形式提供，请咨询PM/RD接口人 |
| ext | string | dsp自定义字段 | 选填(开屏使用，落地页里宏替换) |
| templeid | string | 模板id | 选填(开屏未使用) |
| dealid | string | 订单id | 选填(开屏必填) |
| tagid | string | 广告位id,本次出价参与竞价的目标广告位 | 选填 |
| mmamonitor | MmaMonitor | MMA监测链接 | 选填(开屏未使用) |
| click_through_url | string | 落地页 | 选填(开屏使用，落地页) |
| deeplink_url | string | deeplink url | 选填(开屏使用，deeplink url) |
| source_url | string | 开屏免审物料url | 选填(开屏免审使用，展现物料) |
| material_md5 | string | 开屏免审物料md5 | 选填(开屏使用，免审物料md5) |
返回字段示例
{
"id": "1569628278785885030",
"seatbid": [{
"bid": [{
"id": "47ef160a8dc70463540200003bb04809af2ecd31_0",
"impid": "1569628278785885030",
"price": 3574.0,
"adid": "14916818",
"nurl": "https://xxx.xxx.xxx",
"impurl": ["https://xxx.xxx.xxx1","https://xxx.xxx.xxx2"],
"ext": "47ef160a8dc70463540200003bb04809af2ecd31_0",
"expurl": ["https://xxx.xxx.xxx1","https://xxx.xxx.xxx2"],
"dealid": "100338",
"tagid": "735",
"click_through_url":"xxxxxxxxxxxxxxxxx",
"deeplink_url":"xxxxxxxxxxxxxxxxx",
"source_url":"xxxxxxxxxxxxxxxxx",
"material_md5":"xxxxxxxxxxxxxxxxx"
"mmamonitor": {}
}]
}],
"bidid": "9ef2521520744ea6823f330a49a5b62c",
"resmicrotime": "1661257613637"
}
MmaMonitor object详细字段及含义：
| 字段名称 | 类型 | 描述 | 字段必填 |
|---|---|---|---|
visible_show | array of string | 图文物料可见监测，每个物料最多支持3条链接，单条链接最多1024个字符(仅图文类物料支持，非图文忽略该字段) | 选填 |
start_play | array of string | 视频物料，视频开始播放事件监测，每个物料最多支持3条链接，单条链接最多1024个字符(仅视频类物料支持，非视频物料忽略该字段) | 选填 |
visible_play | array of string | 视频物料满足可见播放时上报，每个物料最多支持3条链接，单条链接最多1024个字符（仅视频类物料支持，非视频物料忽略该字段） | 选填 |
2.3 Win Notice
对竞标成功的广告物料发送获胜通知（win notice url），协议为 HTTP GET。支持DSP可以通过宏替换来定义每次竞标的win notice url（即Bid response中的nurl字段）。如果nurl为空，则发送DSP在账号注册时提供的默认win notice url。目前支持的宏如下：
| 参数 | 描述 | 字段必填 |
|---|---|---|
__IMPID__ | 曝光ID | 选填 |
2.4 Imp Notice
对实际曝光的广告物料发送曝光通知（imp notice url），协议为 HTTP GET。支持DSP可以通过宏替换来定义每次曝光的imp notice url（即Bid response中的impurl字段）。如果impurl为空，则发送上传物料时提供的默认imp notice url。imp notice url限制最多支持3条，每条限制长度不大于1024个字符，不符合条件或者多余的url将直接被过滤掉。目前支持的宏如下：
| 参数 | 描述 | 字段必填 |
|---|---|---|
__IMPID__ | 曝光ID | 选填 |
2.5 Click Notice
对实际点击的广告物料发送点击通知（click notice url），协议为 HTTP GET。支持DSP可以通过宏替换来定义每次曝光的click notice url（即Bid response中的expurl字段）。如果expurl为空，则发送DSP在账号注册时提供的默认click notice url。click notice url限制最多支持3条，每条限制长度不大于1024个字符，不符合条件或者多余的url将直接被过滤掉。目前支持的宏如下：
| 参数 | 描述 | 字段必填 |
|---|---|---|
__IMPID__ | 曝光ID | 选填 |
2.6 MMA SDK Notice
投放手机百度APP主列表页的广告，支持MMA SDK监测上报，其中visible_show为图文样式的可见曝光监测链接，start_play为视频样式开始播放的监测链接，visible_play为视频满足可见播放的监测链接，MMA监测链接已替换原vshowurl和vplayurl，使用MMA监测的同时，也支持普通曝光(impurl)上报，MMA监测支持宏替换，不支持302跳转，监测链接必须是http://或https://开头，超出数量限制或长度限制的链接将被抛弃。（注：现阶段仅PD模式支持MMA上报，PDB订单的物料请勿使用MMA监测）
3 Proto定义
proto定义文件下载请跳转：附件下载
4 开屏支持的能力
4.1 支持自定义dealid
支持将广告主自定义的dealid和百度侧的dealid关联起来,即请求中BidRequest::Imp::dealidlist填充的是广告主的自定义dealid
4.2 多deal
支持一次请求中发送多个dealid给广告主，即请求BidRequest::Imp::dealidlist中填充多个dealid，广告主在返回的BidResponse::SeatBid::Bid中填充每个要量的deal
4.3 免审
免审即为展现的物料由外部返回，需要将展现物料填充到BidResponse::SeatBid::Bid::source_url中，material_md5填写物料的md5
4.6 落地页、展现监测和点击监测实时返回
落地页填充到BidResponse::SeatBid::Bid::click_through_url; 展现监测链接填充到BidResponse::SeatBid::Bid::impurl; 点击监测链接填充到BidResponse::SeatBid::Bid::clc_tracking_url