BidRequest
Cloud-DSP收到的HTTP竞价请求信息保存在BidRequest中,BidRequest用protobuf(Google Protobuf)实现,本节将介绍BidRequest对象。
2.1 BidRequest Object
BidRequest对象是一次竞价请求的主体内容,包含了此次请求的设备信息、用户信息、位置信息、广告展示时机信息等,具体结构如下:
Field | Type | Description |
---|---|---|
id | string | 必填,标识一次请求的唯一ID |
imp | object[] | 必填,数组格式,一个完整的BidRequest必须包含至少一个Imp对象 |
site | object | 条件必填,当前竞价请求发自某个站点时,必须提供完整的Site对象 |
app | object | 条件必填,当前竞价请求发自某个应用时,必须提供完整的App对象 |
device | object | 必填,发起当前竞价请求的设备信息,Device对象中包含了大量必填信息,需要注意 |
user | object | 条件必填,当前竞价请求发自某个站点时,必须提供User对象;其他情况推荐填充User对象 |
bcat | string[] | 可选,描述当前竞价请求屏蔽的广告分类,具体分类方式参见附录IAB分类信息表 |
badv | string[] | 可选,描述当前竞价请求屏蔽的广告主域名 |
query | string | 条件必填,当前竞价请求发自搜索广告场景时,必须提供完整的query信息描述当前搜索的关键词 |
说明
- 必填:该字段在当前对象中必须存在
- 条件必填:在特定条件下,该字段在当前对象中必须存在
- 推荐:推荐填写,该字段在后续环节中会被使用,准确的填写能够有效提高当前对象的可用性
- 可选:可以缺失的字段,一般情况下字段缺失将被系统解析为“未知”
下文中出现同样字段均参见此说明
2.2 Imp Object
Imp对象描述了一个广告位的相关信息,具体分为了广告位属性信息和竞价信息两方面。
一个BidRequest对象可以包含多个Imp对象,在填充BidRequest的时候,每种独立的广告展示场景都需要使用独立的Imp去进行描述。
Field | Type | Description |
---|---|---|
id | string | 必填,标识一个Imp对象的唯一ID |
banner | object | 条件必填,当前广告展现机会是一个横幅广告位时,必须提供完整的Banner对象 |
video | object | 条件必填,当前广告展现机会是一个视屏广告位时,必须提供完整的Video对象 |
native | object | 条件必填,当前广告展现机会是一个原生广告位时,必须提供完整的Native对象 |
bidinfo | object[] | 必填,当前广告位的竞价信息,描述了当前广告位可接受的广告竞价类型和最低出价信息;可以通过数组的方式描述多组竞价信息 |
slottype | object | 必填,SlotType对象,描述当前广告位的类型信息 |
slotid | string | 必填,当前Imp所对应的广告位ID,DSP在使用该字段前,需要和流量供应方约定好slotid的字符串拼接格式 |
说明
- 一个完整的Imp对象必须拥有Banner、Video、Native三个对象中的一个,且最多只拥有一个。
- ssp将来自广告位ID(1001)的一个Imp通过Adx发送给Dsp,建议Ssp将slotid字段填充为${sspname}_1001。 Dsp在做广告位定向之前需要和Ssp预先确认好有哪些广告位可能需要被定向。 否则由Ssp发送的slotid可能不能被Dsp识别。
2.2.1 Banner Object
Banner对象描述了一个横幅类广告位的基本信息。
Field | Type | Description |
---|---|---|
w | int | 必填,广告位宽度;如果wmax和wmin均未设置,则表示请求广告物料宽度必须等于该值;如果设置了wmax或wmin,则表示请求广告物料宽度推荐等于该值 |
h | int | 必填,广告位高度;如果hmax和hmin均未设置,则表示请求广告物料高度必须等于该值;如果设置了hmax或hmin,则表示请求广告物料高度推荐等于该值 |
wmax | int | 可选,广告位允许的最大物料宽度,缺省状态标识不限制 |
hmax | int | 可选,广告位允许的最大物料高度,缺省状态标识不限制 |
wmin | int | 可选,广告位允许的最小物料宽度,缺省状态标识不限制 |
hmin | int | 可选,广告位允许的最小物料高度,缺省状态标识不限制 |
mimes | string[] | 推荐,广告位允许的物料内容类型,当前主流的mimes包括如下: - image/jpg - image/gif - application/x-shockwave-flash 缺省状态表示允许所有类型 |
2.2.2 Video Object
Video对象描述了一个视频类广告位的基本信息。
Field | Type | Description |
---|---|---|
w | int | 必填,广告位宽度 |
h | int | 必填,广告位高度 |
maxduration | int | 推荐,广告位允许的最大展示时长,单位:秒,缺省状态标识不限制 |
minduration | int | 推荐,广告位允许的最小展示时长,单位:秒,缺省状态标识不限制 |
maxbitrate | int | 推荐,广告位允许的最大播放比特率,单位:Kbps,缺省状态标识不限制 |
minbitrate | int | 推荐,广告位允许的最小播放比特率,单位:Kbps,缺省状态标识不限制 |
mimes | string[] | 推荐,广告位允许的物料内容类型,当前主流的mimes包括如下: - video/x-ms-wmv - video/x-flv 缺省状态标识允许所有类型 |
linearity | object | 推荐,VideoLinearity对象,描述广告在当前视频中的展现形式 |
startdelay | int | 推荐,广告播放时机: -2: 视频播放完成时 -1: 视频播放中间 0: 视频播放开始前 >0: 视频播放开始后延迟时间,单位:秒 |
2.2.2.1 VideoLinearity Object
VideoLinearity对象描述了视频广告在视频播放器中的展现形式的枚举值信息。
Value | Description |
---|---|
LINEAR | 在播放器中覆盖原视频直接播放 |
NON_LINEAR | 在播放器中通过悬浮窗的形式展现 |
2.2.3 Native Object
Native对象描述了一个原生类广告位的基本信息。
Field | Type | Description |
---|---|---|
assets | object[] | 必填,原生广告所需要的物料元素 |
2.2.3.1 Asset Object
Asset对象描述了原生广告位的一组物料元素诉求。
Field | Type | Description |
---|---|---|
id | int | 必填,标识物料元素诉求的唯一ID |
required | bool | 必填,标识该物料元素诉求是否必须满足,如果设置为True,则会过滤所有不满足诉求的原生物料 |
title | object | 条件必填,当前诉求描述的是广告标题相关信息时,必须提供完整的Title对象 |
img | object | 条件必填,当前诉求描述的是广告图片相关信息时,必须提供完整的Image对象 |
data | object | 条件必填,当前诉求描述的是其他元素信息时,必须提供完整的Data对象 |
说明
一个完整的Asset对象必须拥有Title、Image、Data三个对象中的一个,且最多拥有一个。
2.2.3.1.1 Title Object
Title对象描述了原生广告标题元素的竞价诉求信息。
Field | Type | Description |
---|---|---|
len | int | 必填,可以接受的最大标题长度 |
2.2.3.1.2 Image Object
Image对象描述了原生广告图片元素的竞价诉求信息。
Field | Type | Description |
---|---|---|
type | Object | 必填,ImageAssetType对象,描述当前图片的用途信息 |
w | int | 必填,图片宽度;如果未设置wmin,则表示图片物料宽度必须等于该值;如果设置了wmin,则表示图片物料宽度推荐等于该值 |
h | int | 必填,图片高度;如果未设置hmin,则表示图片物料高度必须等于该值;如果设置了hmin,则表示图片物料高度推荐等于该值 |
wmin | int | 可选,允许的最小图片宽度,缺省状态标识不限制 |
hmin | int | 可选,允许的最小图片高度,缺省状态标识不限制 |
wmax | int | 可选,允许的最大图片宽度,缺省状态标识不限制 |
hmax | int | 可选,允许的最大图片高度,缺省状态标识不限制 |
mimes | sting[] | 推荐,允许的图片内容类型,当前主流的mimes包括如下: - image/jpg - image/gif 缺省状态表示允许所有类型 |
2.2.3.1.2.1 ImageAssetType Object
ImageAssetType对象描述了原生广告竞价诉求中的图片元素的用途枚举信息。
Value | Description |
---|---|
ICON | 图标,小图片 |
LOGO | 标志、商标等 |
MAIN | 主图,大图片 |
2.2.3.1.3 Data Object
Data对象描述了原生广告竞价诉求中对其他类型元素的诉求信息。
Field | Type | Description |
---|---|---|
type | object | 必填,DataAssetType对象,描述当前元素类型 |
len | int | 条件必填,当前对象描述类型为可显示文本类型时,必须提供len信息用于描述最长可接受文本长度 |
2.2.3.1.3.1 DataAssetType Object
DataAssetType对象描述了原生广告竞价诉求中的其他元素的类型枚举信息。
Value | Description |
---|---|
SPONSORED | 赞助商信息 |
DESC | 创意描述信息 |
RATING | 应用、商品推广时所需的排序信息 |
LIKES | 应用、商品推广时所需的‘赞’数量信息 |
DOWNLOADS | 应用推广时所需的下载量信息 |
PRICE | 商品推广的原始售价信息 |
SALEPRICE | 商品推广的打折后售价信息 |
PHONE | 创意中可用到的电话信息 |
ADDRESS | 创意中可展示的地址信息 |
DESC2 | 创意描述信息,用于对DESC的补充,或用于显式在两段描述中换行 |
DISPLAYURL | 展示在创意中的URL信息 |
CTATEXT | 创意的CTA文本信息 |
2.2.4 BidInfo Object
BidInfo对象描述了当前广告位对竞价类型、底价的诉求信息。
Field | Type | Description |
---|---|---|
bidtype | int | 必填,描述当前广告位可以接受的竞价类型信息,具体值定义参见BidType对象 |
bidfloor | int | 推荐,描述当前广告位可以接受的对应竞价类型的底价信息,单位:分。其中CPT竞价方式不能设置底价。缺省状态标识不对底价进行限制。 |
2.2.4.1 BidType Object
BidType对象描述了当前广告位可接受的竞价类型的枚举信息。
Value | Description |
---|---|
CPM | 按展现计费 |
CPC | 按点击计费 |
CPD | 按下载计费 |
CPT | 按时间包断计费 |
说明
- 按下载计费(CPD)中的下载动作,需要在系统中进行具体定义,当前系统默认的实现方式是下载行为开始即计费。可选的动作类型包括了下载开始、下载进行中、下载完成,这些动作类型均需要用户端能够及时的回传事件日志才可以获取。
- 按时间包断计费(CPT)中的时间段长度可以在系统中自行定义,当前系统默认的实现方式是按天包断计费。
2.2.5 SlotType Object
SlotType对象描述了广告位类型的枚举值信息。
Value | Description |
---|---|
SLOT_FIEXD | 横幅固定广告位 |
SLOT_STARTUP | 应用开屏广告位 |
SLOT_INTERSTITIAL | 应用插屏广告位 |
SLOT_VIDEO | 视屏流广告位 |
SLOT_NATIVE | 原生广告位 |
SLOT_FLOATING | 横幅悬浮广告位 |
2.3 Site Object
Site对象描述了发起当前竞价请求的站点信息。
Field | Type | Description |
---|---|---|
id | string | 必填,发起当前请求的站点唯一ID。一般站长在广告平台进行注册的时候,平台会为每个站点分配唯一的ID |
name | string | 必填,当前站点的名称 |
domain | string | 必填,当前站点的域名 |
cat | string[] | 推荐,当前站点的分类信息,参见附录IAB分类信息表,通过数组形式表述多种类型 |
quality | string | 可选,当前站点的质量信息,缺省状态会将当前站点的质量属性设置为系统默认值 |
page | string | 必填,当前页面的URL |
pagecat | string[] | 推荐,当前页面的分类信息,参见附录IAB分类信息表,通过数组形式表述多种类型 |
pagequality | string | 可选,当前页面的质量信息,缺省状态会将当前页面的质量属性设置为系统默认值 |
pagetype | string | 可选,当前页面的类型信息,包括:资讯页、论坛页等,缺省状态为系统默认类型 |
ref | string | 必填,当前页面的referrer url |
keywords | string | 推荐,当前页面的关键词信息,通过逗号分隔表述多个关键词信息 |
说明
- domain字段涉及到Cloud-DSP的域名定向相关业务
2.4 App Object
App对象描述了发起当前竞价请求的应用信息。
Field | Type | Description |
---|---|---|
id | string | 必填,发起当前请求的应用唯一ID。一般开发者在广告平台进行注册的时候,平台会为每个应用分配唯一的ID |
name | string | 必填,当前应用的名称 |
domain | string | 推荐,当前应用的域名 |
cat | string[] | 推荐,当前应用的分类信息,参见附录IAB分类信息表,通过数组形式表述多种类型 |
quality | string | 可选,当前应用的质量信息,缺省状态会将当前应用的质量属性设置为系统默认值 |
pagecat | string[] | 推荐,当前应用页的分类信息,参见附录IAB分类信息表,通过数组形式表述多种类型 |
pagequality | string | 可选,当前应用页的质量信息,缺省状态会将当前应用页的质量属性设置为系统默认值 |
ver | string | 必填,当前应用的版本信息 |
bundle | string | 必填,当前应用的包名 |
paid | bool | 推荐,当前应用是否是付费应用,缺省状态标识当前应用是免费应用 |
keywords | string | 推荐,当前应用的关键词信息,通过逗号分割表述多个关键词信息 |
storeurl | string | 推荐,当前应用在应用商店的页面URL |
说明
- domain字段涉及到Cloud-DSP的域名定向相关业务
2.5 Device Object
Device对象描述了发起当前竞价请求的设备信息。
Field | Type | Description |
---|---|---|
dnt | bool | 推荐,“Do Not Track”标记 |
ua | string | 条件必填,对于从网页中发起的竞价请求,必须提供完整的ua信息;描述发起当前竞价请求的浏览器User Agent |
ip | string | 必填,当前设备的IP信息 |
ipv6 | string | 推荐,当前设备的IPv6信息可以获取的时候,推荐同时填充ip和ipv6字段 |
geo | object | 推荐,Geo对象,描述当前设备的定位信息 |
did | string | 条件必填,设备号(IMEI)信息。当竞价请求发自Android设备时,会要求填充did、dpid、mac三类信息中至少一类 |
didsha1 | string | 条件必填,设备号(IMEI)信息的sha1哈希值,在必须填充did的时候,可以通过填充didsha1代替 |
didmd5 | string | 条件必填,设备号(IMEI)信息的md5哈希值,在必须填充did的时候,可以通过填充didmd5代替 |
dpid | string | 条件必填,Android-id信息。当竞价请求发自Android设备时,会要求填充did、dpid、mac三类信息中至少一类 |
dpidsha1 | string | 条件必填,Android-id的sha1哈希值,在必须填充dpid的时候,可以通过填充dpidsha1代替 |
dpidmd5 | string | 条件必填,Android-id的md5哈希值,在必须填充dpid的时候,可以通过填充dpidmd5代替 |
mac | string | 条件必填,设备MAC信息。当竞价请求发自Android设备时,会要求填充did、dpid、mac三类信息中至少一类;当竞价请求发自Apple设备时,会要求填充idfa、mac中至少一类信息;当竞价请求发自其他设备时,会推荐填充mac信息 |
macsha1 | string | 条件必填,设备MAC信息的sha1哈希值,在必须填充mac的时候,可以通过填充macsha1代替 |
macmd5 | string | 条件必填,设备MAC信息的md5哈希值,在必须填充mac的时候,可以通过填充macmd5代替 |
idfa | string | 条件必填,Apple设备的IDFA信息。当竞价请求发自Apple设备时,会要求填充idfa、mac中至少一类信息 |
idfasha1 | string | 条件必填,Apple设备的IDFA信息的sha1哈希值,在必须填充idfa的时候,可以通过填充idfasha1代替 |
idfamd5 | string | 条件必填,Apple设备的IDFA信息的md5哈希值,在必须填充idfa的时候,可以通过填充idfamd5代替 |
carrier | object | 条件必填,当竞价诉求发自移动设备时,需要提供完整的Carrier对象来描述当前运营商信息 |
make | string | 推荐,当前竞价请求发自移动设备时,推荐填充完整的make信息来描述当前设备的制造商信息 |
model | string | 推荐,当前竞价请求发自移动设备时,推荐填充完整的model信息来描述当前设备的型号信息 |
os | object | 推荐,OS对象,描述当前设备的操作系统信息 |
osv | string | 推荐,当前设备操作系统的版本号信息 |
w | int | 推荐,当前设备显示屏的高度 |
h | int | 推荐,当前设备显示屏的宽度 |
connectiontype | object | 必填,发起当前竞价请求的设备网络连接类型信息 |
devicetype | object | 必填,发起当前竞价请求的设备类型信息 |
说明
- ua字段涉及到Cloud-DSP的浏览器定向相关业务
- ip字段涉及到Cloud-DSP的地域定向、运营商定向等相关业务
- geo字段设计到Cloud-DSP的地域定向、商圈定向等相关业务
- carrier字段涉及到Cloud-DSP的运营商定向相关业务
- make字段涉及到Cloud-DSP的制造商定向、机型定向等相关业务
- model字段涉及到Cloud-DSP的机型定向等相关业务
- os、osv字段涉及到Cloud-DSP的操作系统定向等相关业务
- connectiontype字段涉及到Cloud-DSP的网络类型定向相关业务
- devicetype字段涉及到Cloud-DSP的设备类型定向相关业务
- did、dpid、mac、idfa字段涉及到Cloud-DSP的人群定向及各类人群特征相关业务
2.5.1 Geo Object
Geo对象描述了当前设备的定位信息。
Field | Type | Description |
---|---|---|
type | object | 必填,LocationType对象,描述当前定位信息的消息来源类型 |
lat | float | 条件必填,当前定位信息通过GPS获取时,必须提供完整的纬度信息 |
lon | float | 条件必填,当前定位信息通过GPS获取时,必须提供完整的经度信息 |
country | string | 推荐,发起请求时设备所在国家信息 |
prov | string | 推荐,发起请求时设备所在省份信息 |
city | string | 推荐,发起请求时设备所在城市信息 |
2.5.1.1 LocationType Object
LocationType对象描述了当前定位来源类型的枚举值。
Value | Description |
---|---|
GPS_LOCATION | 通过GPS信息定位 |
IP | 通过用户IP辅助定位 |
USER_PROVIDED | 用户自主提供定位信息 |
2.5.2 Carrier Object
Carrier对象描述当前设备的网络运营商类型的枚举值。
Value | Description |
---|---|
CARRIER_CHINA_TELECOM | 中国电信 |
CARRIER_CHINA_MOBILE | 中国移动 |
CARRIER_CHINA_UNICOM | 中国联通 |
CARRIER_CHINA_NETCOM | 中国网通 |
说明
更多的运营商类型可以通过修改接口协议进行扩展
2.5.3 OS Object
OS对象描述当前设备的操作系统类型的枚举值。
Value | Description |
---|---|
WINDOWS | Windows操作系统,包含PC和移动版本 |
MACOS | Apple PC设备的操作系统 |
LINUX | Linux操作系统 |
IOS | Apple移动设备的操作系统 |
ANDROID | Android操作系统 |
说明
更多的操作系统发行版可以通过修改接口协议进行扩展
2.5.4 ConnectionType Object
ConnectionType对象描述当前设备的网络接入类型的枚举值。
Value | Description |
---|---|
WIFI | Wi-Fi无线网络 |
CELL_2G | 移动网络2G |
CELL_3G | 移动网络3G |
CELL_4G | 移动网络4G |
ETHERNET | 有线网络 |
2.5.5 DeviceType Object
DeviceType对象描述当前设备类型的枚举值。
Value | Description |
---|---|
PERSONAL_COMPUTER | 个人计算机 |
PHONE | 手机设备 |
TABLET | 平板设备 |
2.6 User Object
User对象描述了发起当前竞价请求的用户信息。
Field | Type | Description |
---|---|---|
id | string | 条件必填,当前竞价请求发起方持有的用户ID,在网页环境下,该ID一般为用户的cookie |
yob | int | 推荐,当前用户的出生年份信息,四位数字表示 |
gender | string | 推荐,当前用户的性别信息 M - 男 F - 女 缺省 - 未知 |
keywords | string | 推荐,当前用户的关键词、兴趣点信息,通过逗号分割表述多个关键词信息 |