实时检索对接

更新日志

编号日期作者修改内容
12019-08-18lihuifeng01整合RTB、信息流PDB&PD、开屏PDB&PD检索bid协议
输出统一对接文档
22019-11-05lihuifeng01新增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结构如下图所示：

image.png

BidRequest object详细字段及含义

字段名称类型描述字段必填
idstring请求ID必填
imparray of Imp objects曝光对象，一次request可以包含多个imp(开屏中一个imp对应一个广告位的请求)选填
appApp objectAPP信息选填
deviceDevice设备信息选填
atint32竞价方式, PDB&PD为定价, 此字段不传, RTB当前只支持二价选填(开屏未使用)
tmaxint32超时时间选填(开屏未使用)
extstring百度与接入方约定的定制化信息选填(开屏未使用)
trans_info_listarray of GeneralTransInfo objects特殊字段/附加字段,key-value形式选填(开屏未使用)

Imp object，开屏广告请求包含Banner对象，信息流包含Native对象:

字段名称类型描述字段必填
idstring曝光 ID必填
tagidstring广告位ID,详见《广告位列表》开屏广告未填充该字段，RTB必传
bidfloordouble竞价底价，单位是分/千次曝光，即CPM开屏广告未填充该字段，RTB必传
securebool标识是http还是https,0 = non-secure, 1 = secure选填(开屏未使用)
campaign_datestring预投放日期,如"20160602"选填（仅开屏PDB&PD使用）
bannerBanner objectbanner类型的广告位选填（仅开屏填充长宽信息）
nativeNative objectnative类型的广告位选填(仅信息流填充)
templelistarray of string流量支持的模板ID列表,详见《物料规格》选填(开屏未使用)
dealidlistarray of string订单ID列表(经百度筛选后可选的订单ID列表)选填（PDB&PD模式必填，repeated类型，一个Imp中可能包含多个dealid）
adidlistarray该流量可选的adid list暂未使用

Banner object详细字段及含义：

字段名称类型描述字段必填
wint32广告位宽度选填
hint32广告位高度选填
posint32banner位置选填(开屏未使用)

Native object详细字段及含义：

字段名称类型描述字段必填
request_nativeNativeRequest object选填

NativeRequest object 详细字段及含义:

字段名称类型描述字段必填
plcmtcntint32广告物料的个数（RTB填充）选填

App object详细字段及含义：

字段名称类型描述字段必填
app_namestringapp name选填
verstringApplication version选填(开屏未使用)
bundlestringpackage name选填(开屏未使用)
package_namestring应用包名, 例如：com.moji.MojiWeather选填
categoryarray of stringapp类目选填

Device object详细字段及含义：

字段名称类型描述字段必填
uastringuser agent选填
ipstringIPV4地址选填
ipv6stringIPV6地址选填(开屏未使用)
geoGeo object实时位置信息选填(开屏未使用)
modelstringdevice model选填
osstring设备平台 ‘ios’/‘android’选填
osvstring操作系统版本选填
wint32屏幕宽度选填(开屏未使用)
hint32屏幕高度选填(开屏未使用)
connectiontypeConnectionType网络类型选填
devicetypeDeviceType设备类型选填
idfastringiOS设备的IDFA明文（全大写）选填
oaidstringAndroid 10以上设备oaid明文选填
imei_md5stringAndroid设备imei设备号md5加密串（32位大写）选填
android_idstringAndroid设备AndroidId选填(开屏未使用)

Geo object详细字段及含义：

字段名称类型描述字段必填
latdouble选填
londouble选填
typeLocationType选填

GeneralTransInfo object详细字段及含义:

字段名称类型描述字段必填
keystring必填
valuestring选填
value_listarray of Pair objects数组形式的内容选填

Pair object详细字段及含义:

字段名称类型描述字段必填
keystring选填
valuestring选填
#### trans_info_list传递字段说明: | 字段名称(key属性值) | value | 含义 | 字段必填 | | - | - | - | - | | reqmicrotime | 毫秒时间 | 请求下发时的服务器时间,精确到毫秒 | 选填 | | forum_name | 吧名 | 来自贴吧的广告请求,若有吧名,则写入该字段 | 选填 |

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结构如下图所示：

image.png

BidResponse object详细字段及含义：

字段名称类型描述字段必填
idstring请求ID必填
bididstring对应的bidder response id,debug string选填(开屏未使用)
seatbidarray of SeatBid objects所有广告信息(开屏中一个seatbid对应一个Imp)选填(开屏必填)
resmicrotimestring下游bid响应发出的时间戳（精确到毫秒）选填(开屏未使用)

SeatBid object详细字段及含义：

字段名称类型描述字段必填
bidarray of Bid objects对应到imp选填(开屏必填)

Bid object详细字段及含义：

字段名称类型描述字段必填
idstringbidder response id必填
impidstring对应的曝光ID必填
pricefloat出价价格，单位是分/千次曝光，即CPM（PDB&PD模式均为定价投放, 该字段值被忽略）必填
adidstring需求方针对此流量选择下发的广告id（广告id是需求方上传物料时,由百度生成并返回的adid）必填
nurlstring竞价成功通知选填(开屏未使用)
impurlarray of stringimp notice url选填
expurlarray of stringclick notice url选填
admstring广告素材,json序列化的字符串（投放信息流PDB/PD/RTB，如果合作方以先投后审方式接入，则需填充该字段）选填(开屏未使用)，该字段数据格式目前以表格形式提供，请咨询PM/RD接口人
extstringdsp自定义字段选填(开屏未使用)
templeidstring模板id选填(开屏未使用)
dealidstring订单id选填(开屏必填)
tagidstring广告位id,本次出价参与竞价的目标广告位选填(开屏未使用)
mmamonitorMmaMonitorMMA监测链接选填(开屏未使用)

MmaMonitor object详细字段及含义：

字段名称类型描述字段必填
visible_showarray of string图文物料可见监测，每个物料最多支持3条链接，单条链接最多1024个字符(仅图文类物料支持，非图文忽略该字段)选填
start_playarray of string视频物料，视频开始播放事件监测，每个物料最多支持3条链接，单条链接最多1024个字符(仅视频类物料支持，非视频物料忽略该字段)选填
visible_playarray 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定义文件下载请跳转：附件下载

←物料推送审核广告位列表→