OpenRTB 2.3.1协议规范 - yushicong/doc GitHub Wiki
1.Bid_Request竞价请求
Bid-Request（竞价请求对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| id | String | 是 | 竞价请求id | |
| imp | Object[] | 是 | 描述一个广告位对象 | 至少一个曝光对象 |
| site | Object | 否 | 媒体站点对象 | |
| app | Object | 否 | 移动app站点对象 | |
| device | Object | 否 | 设备对象 | |
| user | Object | 否 | 用户对象 | |
| test | integer | 否，默认0 | 是否测试 | 0是正式，1是测试，默认是0 |
| at | integer | 否，默认2 | 拍卖类型 | 1是FirstPrice，2是Second Price Plus，默认是2，交换拍卖类型可以定义使用值 |
| tmax | integer | 否 | 最长时间等待 | 最长时间以毫秒为单位提交,以避免超时。这个值通常是线下沟通。 |
| wseat | String[] | 否 | 商家白名单 | 白名单的商家才允许买家出价这个广告，seatIds（商家id） 需与DSP沟通，若空则没有限制 |
| allimps | integer | 否，默认0 | 是否响应imp全部有效 | 0 是 no or unknown, 1 是 yes |
| cur | String[] | 否 | 允许参与出价的货币币种 | 使用 ISO-4217 国际标准货币代码 |
| bcat | String[] | 否 | 阻止的广告类别 | 参考官方文档2.3.1版本，5.1章节详细列表类型参数 |
| badv | String[] | 否 | 阻止广告，通过广告的domains | e.g., “ford.com” |
| regs | Object | 否 | 监管条件对象 | |
| ext | Object | 否 | 扩展站位对象 |
Imp（描述广告位对象-曝光对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| id | String | 是 | 曝光id | 不是广告位id |
| banner | Object | 否 | banner类型的广告位对象 | 横幅类型 |
| video | Object | 否 | video类型的广告位对象 | 视频类型 |
| native | Object | 否 | native类型的广告对象 | 原生类型 |
| displaymanager | String | 否 | 中介的合作伙伴 | eg：推荐视频和/或应用程序 |
| displaymanagerver | String | 否 | 中介的合作伙伴版本 | eg:推荐视频和/或应用程序 版本 |
| instl | integer | 否，默认0 | 这个广告是否有间隙 | 1 是 the ad is interstitial or full screen, 0 是 not interstitial. |
| tagid | String | 否 | 广告位ID | 标识符为特定的广告或广告位置标记用于竞价拍卖 |
| bidfloor | float，默认0 | 否 | 广告位底价，单位是：分/CPM | |
| bidfloorcur | String | 否，默认USD | 广告位底价的货币币种 | 使用 ISO-4217 国际标准货币代码 |
| secure | integer | 否 | 安全状态（需要安全的HTTPS URL） | 0 不安全, 1 安全 |
| iframebuster | String[] | 否 | 数据交换的名称，用于支持购买者的iframe | |
| pmp | Object | 否 | 管理协议规则对象 | |
| ext | Object | 否 | 扩展站位对象 |
banner（banner类型的广告位对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| w | integer | 否 | 广告位宽度 | |
| h | integer | 否 | 广告位高度 | |
| wmax | integer | 否 | 最大宽度 | |
| hmax | integer | 否 | 最大高度 | |
| wmin | integer | 否 | 最小宽度 | |
| hmin | integer | 否 | 最小高度 | |
| id | String | 否 | 横幅广告id | |
| btype | integer [] | 否 | 阻止横幅广告通过类型 | 参考官方文档2.3.1版本，5.2章节详细列表类型参数 |
| battr | integer [] | 否 | 阻止创意属性 | 参考官方文档2.3.1版本，5.3章节详细列表类型参数 |
| pos | integer | 否 | 广告位未知，0：未知；1：首屏；2：次屏 | 参考官方文档2.3.1版本，5.4章节详细列表类型参数 |
| mimes | integer [] | 否 | 内容支持MIME的类型 | application/x-shockwave-flash，image/jpg，image/gif |
| topframe | integer | 否 | 广告是0：iframe，1：顶部 frame | |
| expdir | integer [] | 否 | 广告可能的方向扩展 | 5.5章节详细列表类型参数，1：left 2：right 3：up 4：down 5：full screen |
| api | integer [] | 否 | 支持广告的api有哪些 | 参考官方文档2.3.1版本，5.6章节详细列表类型参数 |
| ext | Object | 否 | 扩展站位对象 |
video（video类型的广告位对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| mimes | string [] | 是 | 内容支持MIME的类型 | video/x-ms-wmv，video/x-flv |
| minduration | integer | 否 | 最小的视频广告持续时间以秒为单位 | |
| maxduration | integer | 否 | 最大的视频广告持续时间以秒为单位 | |
| protocol | integer | 否 | 官方（已弃用） | |
| protocols | integer[] | 否 | 数组支持的视频投标响应协议 | 参考官方文档2.3.1版本，5.8章节详细列表类型参数 |
| w | integer | 否 | 视频播放器的宽度(以像素为单位) | |
| h | integer | 否 | 视频播放器的高度(以像素为单位) | |
| startdelay | integer | 否 | 该字段仅在linearity=1时有效；线性贴片，0：前帖；-1：中贴；-2：后贴。 | 参考官方文档2.3.1版本，5.10章节详细列表类型参数 |
| linearity | integer | 否 | 广告展现样式 | 0: "未知"; 1："instream/linear"即线性贴片素材，包括前贴中贴后贴; 2:"overlay/nonlinear"即视频播放中的悬浮广告; 3："pause"即视频播放暂停中的悬浮广告; 4:"fullscreen"即视频全屏播放时的悬浮广告; |
| sequence | integer | 否 | 如果多个广告提供相同的报价请求，这个字段将允许传递给多个创意人员 | |
| battr | integer[] | 否 | 阻止创意属性 | 参考官方文档2.3.1版本，5.3章节详细列表类型参数 |
| maxextended | integer | 否 | 最大扩展视频广告持续时间是否允许扩展。如果空白或0,扩展是不允许的。如果1,扩展允许的,而且没有时间限。如果大于0,然后扩展的值代表的秒数 | |
| minbitrate | integer | 否 | 最低 bit 速度 | |
| maxbitrate | integer | 否 | 最高 bit 速度 | |
| boxingallowed | integer | 否，默认1 | 4:3的内容到一个16:9的窗口是否允许 | 0：否，1：是 |
| playbackmethod | integer[] | 否 | 允许回放方法 | 参考官方文档2.3.1版本，5.9章节详细列表类型参数 |
| delivery | integer[] | 否 | 支持交付方法 | 参考官方文档2.3.1版本，5.13章节详细列表类型参数 e.g., streaming, progressive |
| pos | integer | 否 | 广告位未知，0：未知；1：首屏；2：次屏 | 参考官方文档2.3.1版本，5.4章节详细列表类型参数 |
| companionad | Object[] | 否 | Array of Banner objects | |
| api | integer[] | 否 | 支持广告的api有哪些 | 参考官方文档2.3.1版本，5.6章节详细列表类型参数 |
| companiontype | integer[] | 否 | companionad对应的广告类型 | 参考官方文档2.3.1版本，5.6章节详细列表类型参数 |
| ext | Object | 否 | 扩展站位对象 |
Native（native类型的广告对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| request | String | 是 | 原生广告的标准规范的请求 | |
| ver | String | 否 | 版本 | |
| api | integer[] | 否 | 支持广告的api有哪些 | 参考官方文档2.3.1版本，5.6章节详细列表类型参数 |
| battr | integer[] | 否 | 阻止创意属性 | 参考官方文档2.3.1版本，5.3章节详细列表类型参数 |
| ext | Object | 否 | 扩展站位对象 |
Site（网站对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| id | String | 否 | 交互网站ID | |
| name | String | 否 | 媒体网站名称 | |
| domain | string [] | 否 | 交互网站的domain | e.g., “mysite.foo.com” |
| sectioncat | string [] | 否 | 描述当前网站片段的内容类别 | 参考官方文档2.3.1版本，5.1章节详细列表类型参数 |
| pagecat | string [] | 否 | 描述当前网站页的内容类别 | 参考官方文档2.3.1版本，5.1章节详细列表类型参数 |
| page | String | 否 | 当前页面URL | |
| ref | String | 否 | Referrer URL | |
| search | String | 否 | 当前页面导航搜索String | |
| mobile | integer | 否 | 移动设备优化表示 | 0：否，1：是 |
| privacypolicy | integer | 否 | 是否网站的隐私政策 | 0：否，1：是 |
| publisher | Object | 否 | 发布者对象 | |
| content | Object | 否 | 视频的内容相关信息。只有视频贴片类型的广告位才会有这个字段 | |
| keywords | String | 否 | 逗号分隔关键字列表 | |
| ext | Object | 否 | 扩展站位对象 |
App（移动app对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| id | String | 否 | 交互App ID | |
| name | String | 否 | 媒体app名称 | |
| bundle | String | 否 | 应用程序包或包名称 | e.g., com.foo.mygame |
| domain | String | 否 | 交互app的domain | e.g., “mygame.foo.com” |
| storeurl | String | 否 | 应用商店安装应用程序URL | |
| cat | string [] | 否 | 内容类别 | 参考官方文档2.3.1版本，5.1章节详细列表类型参数 |
| sectioncat | string [] | 否 | 描述当前网站片段的内容类别 | 参考官方文档2.3.1版本，5.1章节详细列表类型参数 |
| pagecat | string [] | 否 | 描述当前网站页的内容类别 | 参考官方文档2.3.1版本，5.1章节详细列表类型参数 |
| ver | String | 否 | app应用版本 | |
| privacypolicy | integer | 否 | app是否有隐私策略 | 0：否，1：是 |
| paid | integer | 否 | 0：app是免费的，1：app是付费的 | |
| publisher | Object | 否 | 发布者对象 | |
| content | Object | 否 | 视频的内容相关信息。只有视频贴片类型的广告位才会有这个字段 | |
| keywords | String | 否 | 逗号分隔关键字列表 | |
| ext | Object | 否 | 扩展站位对象 |
Publisher（发布者对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| id | String | 否 | 发布者ID | |
| name | String | 否 | 发布者名称 | |
| cat | string [] | 否 | 内容类别 | 参考官方文档2.3.1版本，5.1章节详细列表类型参数 |
| domain | String | 否 | 交互发布者的domain | e.g., “publisher.com” |
| ext | Object | 否 | 扩展站位对象 |
Content（内容对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| id | String | 否 | 唯一标识内容的ID | |
| episode | integer | 否 | 集数量(通常适用于视频内容) | |
| title | String | 否 | 标题名称 | |
| series | String | 否 | 内容系列 | Video Examples: “The Office” (television), “Star Wars” (movie),or “Arby ‘N’ The Chief” (made for web).Non-Video Example: “Ecocentric” (Time Magazine blog). |
| season | String | 否 | 内容,通常视频内容 | e.g., “Season 3” |
| producer | Object | 否 | 发布者对象 | |
| url | String | 否 | 内容的url | |
| cat | string [] | 否 | 内容类别描述内容生产商 | 参考官方文档2.3.1版本，5.1章节详细列表类型参数 |
| videoquality | integer | 否 | 视频质量分类 | 参考官方文档2.3.1版本，5.11章节详细列表类型参数 |
| context | integer | 否 | 内容类型 | 参考官方文档2.3.1版本，5.14章节详细列表类型参数 |
| contentrating | String | 否 | 内容评级 | e.g., MPAA |
| userrating | String | 否 | 用户评级的内容 | e.g., number of stars, likes, etc |
| qagmediarating | integer | 否 | 媒体每QAG评级准则 | 参考官方文档2.3.1版本，5.15章节详细列表类型参数 |
| keywords | String | 否 | 标签关键字 | |
| livestream | integer | 否 | 0 = not live, 1 = content is live | (e.g., stream, live blog). |
| sourcerelationship | integer | 否 | 与广告之间的关系，0 = 间接, 1 = 直接 | |
| len | integer | 否 | 内容以秒为单位的长度，适合视频或音频 | |
| language | String | 否 | 内容使用语言标准ISO-639-1-alpha-2 | |
| embeddable | integer | 否 | 内容是否可嵌入的 | 0：否，1：是 |
| ext | Object | 否 | 扩展站位对象 |
Producer（提供者对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| id | String | 否 | 提供者id | |
| name | String | 否 | 提供者的名字 | |
| cat | string [] | 否 | 内容类别描述内容生产商 | 参考官方文档2.3.1版本，5.1章节详细列表类型参数 |
| domain | String | 否 | 最高级别的domain | e.g.“producer.com” |
| ext | Object | 否 | 扩展站位对象 |
Device（设备对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| ua | String | 否 | user agent(Browser user agent string) | |
| geo | Object | 否 | 地理位置对象 | |
| dnt | integer | 否 | 不跟踪 | 0：跟踪，1：不跟踪 |
| lmt | integer | 否 | 限制广告跟踪 | 0：跟踪无限制，1：跟踪有限制 |
| ip | String | 否 | IP | |
| ipv6 | String | 否 | Ipv6 | |
| devicetype | integer | 否 | 设备类型 | 和0—手机，1—平板，2—PC，3—互联网电视 |
| make | String | 否 | 制造厂商 | 如“apple”“Samsung”“Huawei“，默认为空String |
| model | String | 否 | 型号 | 如”iphoneA1530”，默认为空String |
| os | String | 否 | 操作系统 | 取值如下：Windows: "Windows",Android: "Android",iPhone: "ios",苹果电脑: "Mac" |
| osv | String | 否 | 操作系统版本号 | 如"4.1", "XP"等 |
| hwv | String | 否 | 硬件的设备版本 | e.g., “5S” for iPhone 5S |
| h | integer | 否 | 物理屏幕高度的像素 | |
| w | integer | 否 | 物理屏幕宽度的像素 | |
| ppi | integer | 否 | 屏幕大小 | |
| pxratio | float | 否 | 物理设备独立像素大小的比值 | |
| js | integer | 否 | 是否支持JavaScript | 0：否，1：是 |
| flashver | String | 否 | 版本的Flash支持的浏览器 | |
| language | String | 否 | 浏览语言ISO-639-1-alpha-2 | |
| carrier | String | 否 | 运营商 | 0：wifi；1：中国移动；2：中国联通：3：中国电信；4：其他；5：未识别 |
| connectiontype | integer | 否 | 链接类型 | 0：未知; 1：以太网2：Wifi; 3：移动数据 -未知; 4：2G; 5:3G |
| ifa | String | 否 | IOS设备的唯一标识 | |
| didsha1 | String | 否 | 使用SHA1哈希的Device ID | |
| didmd5 | String | 否 | 使用MD5哈希的Device ID | |
| dpidsha1 | String | 否 | 平台设备ID（SHA1） | |
| dpidmd5 | String | 否 | 平台设备ID（MD5） | |
| macsha1 | String | 否 | 设备mac（SHA1） | hashed via SHA1 |
| macmd5 | String | 否 | 设备mac（MD5） | hashed via MD5 |
| ext | Object | 否 | 扩展站位对象 |
Geo（地理位置对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| lat | float | 否 | 纬度从-90.0 + 90.0,-是南 | |
| lon | float | 否 | 经度-180.0 + 180.0,-是西方。 | |
| type | integer | 否 | 源的位置数据,建议当纬度/经度 | 参考官方文档2.3.1版本，5.16章节详细列表类型参数 |
| country | string | 否 | 城市编码 ISO-3166-1-alpha-3 | |
| region | string | 否 | 地区代码ISO-3166-2 | |
| regionfips104 | string | 否 | 地区代码FIPS 10-4 notation | |
| metro | string | 否 | Google metro code（谷歌地铁编码） | |
| city | string | 否 | 城市使用联合国贸易与运输代码位置 | |
| zip | string | 否 | zip或者邮政编码 | |
| utcoffset | integer | 否 | 本地时间，UTC（世界时间代码） | |
| ext | Object | 否 | 扩展站位对象 |
User（用户对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| id | string | 否 | 用户id | |
| buyeruid | string | 否 | 投标人的uid | |
| yob | integer | 否 | 出生年份4位整数 | |
| gender | string | 否 | 性别 | “M” = male, “F” = female, “O” = known to be |
| keywords | string | 否 | 逗号分隔的列表关键字 | |
| customdata | string | 否 | ||
| geo | Object | 否 | 地理位置对象 | |
| data | Object[] | 否 | 额外的用户数据对象 | |
| ext | Object | 否 | 扩展站位对象 |
Data（数据对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| id | string | 否 | 数据id | |
| name | string | 否 | 数据名称 | |
| segment | Object[] | 否 | 部分对象的数值扩展 | |
| ext | Object | 否 | 扩展站位对象 |
Segment（用户的数据"段"对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| id | string | 否 | 段的id | |
| name | string | 否 | 段的名字 | |
| value | string | 否 | 段的数值 | |
| ext | Object | 否 | 扩展站位对象 |
Regs（监管条件对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| coppa | integer | 否 | 是否隐秘保护规则 | 0：否，1：是 |
| ext | Object | 否 | 扩展站位对象 |
PMP（管理协议规则对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| private_auction | integer | 否 | Deal规则是否生效 | 0 =所有投标被接受,1 =报价仅限于指定的协议和条款 |
| deals | Object[] | 否 | 协议对象 | |
| ext | Object | 否 | 扩展站位对象 |
Deal对象（协议对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| id | String | 是 | deal id | |
| bidfloor | float | 否，默认0 | deal 价格,单位是分/千次曝光,即CPM | |
| bidfloorcur | String | 否，默认USD | 货币指定编码，ISO-4217 alpha codes | |
| at | integer | 否 | 拍卖类型 | 1 = First Price, 2 = Second Price Plus, 3 = the value passed in bidfloor is the agreed upon deal price，其他竞价规则可自己定义 |
| wseat | string[] | 否 | 允许竞标的白名单 | |
| wadomain | string[] | 否 | 允许投标这笔交易domains | 疏忽意味着没有广告限制 |
| ext | Object | 否 | 扩展站位对象 |
2.Bid_Response竞价响应
Bid-Request（竞价请求对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| id | String | 是 | 竞价请求的id | |
| seatbid | Object[] | 否，但若是竞价至少有一个 | 竞价集合对象 | |
| bidid | String | 否 | 投标人响应生成ID协助日志/跟踪 | |
| cur | String | 否，默认USD | 币种 | ISO-4217 alpha codes标准 |
| customdata | String | 否 | 投标人插入的交互cookie | base85 格式，json格式 |
| nbr | integer | 否 | 不竞价的原因 | 参考官方文档2.3.1版本，5.19章节详细列表类型参数 |
| ext | Object | 否 | 扩展站位对象 |
SeatBid（竞价集合对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| bid | Object[] | 是 | 出价对象 | |
| seat | String | 否 | 投标人的对于这个竞价集合的标识 | |
| group | integer | 否，默认0 | 0：一个胜利的曝光对象1：赢得和失败的曝光对象 | |
| ext | Object | 否 | 扩展站位对象 |
bid（出价对象）
| 参数名 | 格式 | 是否必有 | 描述 | 说明 |
|---|---|---|---|---|
| id | String | 是 | 出价id，协助日志/跟踪 | |
| impid | String | 是 | request中的impid | |
| price | float | 是 | 出价，cpm | |
| adid | String | 否 | 广告id | |
| nurl | String | 否 | win notice url，竞价成功提醒url | 支持的“宏”标准 |
| adm | String | 否 | 广告素材URL | |
| adomain | string[] | 否 | 广告商的domain | |
| bundle | String | 否 | 广告应用的包名 | e.g. com.foo.mygame |
| iurl | String | 否 | 进行广告质量/安全检查的url | |
| cid | String | 否 | 活动ID ，以协助广告质量检查 | |
| crid | String | 否 | DSP系统中的创意ID，以协助广告质量检查 | |
| cat | string[] | 否 | 创意的类型 | 参考官方文档2.3.1版本，5.1章节详细列表类型参数 |
| attr | integer[] | 否 | 描述创意广告的属性 | 参考官方文档2.3.1版本，5.3章节详细列表类型参数 |
| dealid | String | 否 | 参考的deal id | |
| h | integer | 否 | 高度创造性的像素 | |
| w | integer | 否 | 宽度创造性的像素 | |
| ext | Object | 否 | 扩展站位对象 |
3.WINNOTICE竞标成功通知
| 参数名 | 格式 | 宏替换 | 描述 | 说明 |
|---|---|---|---|---|
| 参数名 | String | ${AUCTION_ID} | Bid Request ID | 即BidRequest.id |
| 参数名 | String | ${AUCTION_BID_ID} | Bid Response ID per request | 即BidResponse.bidid |
| 参数名 | String | ${AUCTION_IMP_ID} | Impression ID | 即BidRequest.imp.id |
| 参数名 | String | ${AUCTION_SEAT_ID} | 投标人的对于这个竞价集合的标识 | 即BidResponse.seatBid.seat |
| 参数名 | String | ${AUCTION_AD_ID} | 广告id | 既BidResponse.bid.adid |
| 参数名 | float | ${AUCTION_PRICE} | Settlement price，曝光的最终拍卖价，以及时间戳 | |
| 参数名 | String | ${AUCTION_CURRENCY} | 币种 | 使用 ISO-4217 国际标准货币代码 |
| eg：若需要加密处理的格式规则 | String | ${AUCTION_PRICE:B64} | 指定B64加密算法格式 | 若使用加密需要和投标人协商 |