2. 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 推荐,当前用户的关键词、兴趣点信息,通过逗号分割表述多个关键词信息