Vungle OpenRTB 2.3 集成指南

这是“Vungle OpenRTB 2.3 集成指南”的 2.1.0 版(2017 年 8 月)。本文介绍使用 OpenRTB 2.3 与 Vungle Exchange 集成的详细信息。

目录

1.请求和响应

1.1 实体

本部分介绍的所有实体均为 OpenRTB 2.3.1 规范的一部分;如果缺少字段或要求,请默认为属于此规范本身的要求。

1.2 扩展

为了更好地提供广告,Vungle Exchange 提供标准 OpenRTB 协议以外的信息。这些扩展内容不会与现有的 OpenRTB 实现重叠,而是一种补充。扩展内容被划分到其最能发挥作用的各个对象。

所有扩展字段均包含在 OpenRTB 'ext' 对象下名为 'vungle' 的第一级扩展字段的 JSON 对象中。为简单起见,本文档后续部分的文档省略了 'vungle' 字段。下面是一个包含 Vungle 扩展的 OpenRTB JSON 对象的示例:

{
...
"ext": {
"vungle": {
//下方各行中的各个扩展字段。
}
}
}

例如,顶级出价请求对象可能看似这样:

{
"id": "572c3535ab0af400011a721a",
"imp": [{<impression object>}],
"app": {<application object>},
"device": {<device object>},
"user": {<user object>},
"at": 2,
"tmax": 2000,
"cur": ["USD"],
"bcat": ["IAB7-3"],
"badv": ["google.com"],
"ext": {
"vungle": {
"badvid": ["2f00ca35ab0abe4df11da700c"]
}
}
}

1.3 版本控制

随着时间的发展,有些字段已经废弃,因此,为确保兼容性最大化,Vungle Exchange 会谨慎处理最新的 Vungle OpenRTB 规范中指定的所有“弃用”字段。所有“弃用”字段均被安排在下一次规范更新时删除,届时,Vungle Exchange 将不再承担维护弃用字段的责任。

规范中会仍然保留所有删除的字段,但会加上“已删除”标签,指示不再支持该字段。我们使用“已删除”标签来强制确定规范语义:定义之后,每一个字段在规范生命周期内所定义的范围内均是唯一的。这意味着,如果 'id' 字段曾被弃用并从某个规范中删除,它永远不会再以其他含义出现在未来的修订版本中。

1.3.1 语义版本控制

规范的版本控制也将遵守 Semver 2.0.0 指南,即:

  • 主要版本更新可以打破向后兼容;例如,在版本 X 中“弃用”的字段在版本 X+1 中将被“删除”。
  • 次要版本更新不应打破向后兼容;例如,将正在使用的字段标记为“弃用”;或将必填字段标记为“非必填且弃用”。
  • 补丁版本更新则不能打破向后兼容;例如,更正规范描述的拼写错误。

1.请求

2.1 必填字段和可选字段

对即将推出部分的必填列的注释:

  • 是:此类字段的下游用户根据指定的类型可以始终看到格式正确的非空值。
  • 否:此类字段不会为下游用户存在或显示有效值。用户必须对该值进行验证,但不必验证类型。
  • 默认:OpenRTB 2.3.1 中所有未提及的字段均默认为非必填

2.2 协议协商

Vungle Exchange 支持通过协议协商使用 HTTP/2 通信;否则默认为 HTTP/1.1。

2.3 请求头

每个出价请求均有 OpenRTB 协议指定的以下自定义 HTTP 头:

X-OpenRTB-Version: 2.3

除自定义 HTTP 头外,Vungle Exchange 还附加了以下标准头:

Content-Type: application/json; charset=utf-8
Accept: application/json 

最后,Vungle Exchange 将附加一个自定义头来指示 Vungle OpenRTB 规范的版本:

X-Vungle-OpenRTB-Version: 2

2.4 BidRequest 对象

字段 类型 必填 描述
id 字符串

Vungle Exchange 生成的出价请求 ID;例如,'570b0eb14e67c98f761a0ca0'。

imp

对象数组

请参阅展示对象。
app 对象 请参阅应用程序对象。
device 对象 请参阅设备对象。
at 整数

竞拍类型;例如,'2' 代表二价拍卖。Vungle Exchange 只运行二价拍卖,因此此值始终为 '2'。

tmax 整数

提交完整出价响应的最长时间(以毫秒计);此值始终为 '250'。

cur 字符串数组

以 ISO-4217-alpha 显示的允许的拍卖货币的列表;例如,["USD", "CNY", "EUR"]。我们目前只支持 "USD"。

bcat 字符串数组 请参阅 OpenRTB 2.3.1 第 5.1 部分。
regs 对象 请参阅 OpenRTB 2.3.1 第 3.2.16 部分。
test 整数

拍卖处于测试模式 (1) 还是实况模式 (0);测试拍卖不计费。

2.4.1 展示对象

字段 类型 必填 描述
id 字符串 Vungle Exchange 生成的展示 ID;例如,'3a06eb14e67c98f761add01'。
displaymanager 字符串 供应方显示管理器;Vungle 使用此字段来指定所使用的 SDK 技术,因为我们需要区分 SDK 移动平台;例如,'Vungle' for iOS, 'VungleDroid' for Android, and 'VungleWindows' for Windows,后跟下一个字段中的 SDK 版本。
displaymanagerserver 字符串 供应方显示管理器版本;Vungle 使用此字段来指定 SDK 版本;例如,'3.3.1'。
bidfloor 浮动 让出价合格的最低出价价格;例如,'8.72'。
bidfloorcur 字符串 以 ISO-4217-alpha 显示的展示货币;例如,'USD'。
video 对象 请参阅视频对象。
tagid 字符串 与给定展示对应的广告位置 ID;例如,'placement_name_1af44fda'。
instl 整数 展示是否 (0) 表示全屏/插播 (1)。目前,Vungle Exchange 只支持全屏/插播 (1)。
secure 整数 标记以指示展示是否需要安全的 HTTPS URL 创意资产和标记,其中,0 = 不安全,1 = 安全。
ext 对象 Vungle 始终需要安全 (1) 的资产和标记。

2.4.2 视频对象

字段 类型 必填 描述
mimes 字符串数组 支持的内容 MIME 类型。Vungle Exchange 只支持 ["video/mp4"]。
h 整数 视频高度。
w 整数 视频宽度。
minduration 整数 视频必须播放的最少秒数。
maxduration 整数 视频可以播放的最长秒数。
delivery 整数数组 支持的视频交付方式的列表:(进步或流)。请参阅 OpenRTB 2.3.1 第 5.13 部分。
minbitrate 整数 以千位节/秒计的最小出价速度。Vungle Exchange 目前只支持 250。
maxbitrate 整数 以千位节/秒计的最大出价速度;例如,500。
protocols 整数数组 请参阅 OpenRTB 2.3.1 第 5.8 部分;例如,[2, 5]。
boxingallowed 整数 是否 (0) 允许 (1) 将视频装入盒中。此值始终为 '1'。
playbackmethod 整数数组 请参阅 OpenRTB 2.3.1 第 5.9 部分。
startdelay 整数 请参阅 OpenRTB 2.3.1 第 5.10 部分。此值始终为 '0'。

2.4.3 应用程序对象

字段 类型 必填 描述
id 字符串 Exchange 特定 ID。对于 Vungle,此为应用商店 ID;例如,'3709293'。
此 ID 对于 DSP 可能没有任何意义,但 DSP 可能用它来比较和调整报告争议。
bundle 字符串 唯一的市场 ID,这是平台特定的应用程序识别码,对于应用是唯一的,与 Vungle Exchange 无关
- 在 Android 上,这应该是捆绑包或包名称(例如,'com.supercell.hayday')。
- 在 iOS 上,这是一个数字 ID。
publisher 对象 请参阅发布人对象。
name 字符串 应用程序名称;例如,'Hay Day'。
storeurl 字符串 应用商店的 URL;例如,'https://itunes.apple.com/us/app/hay-day/id506627515?mt=8#'。
cat 字符串数组 请参阅 OpenRTB 2.3.1 第 5.1 部分。
privacypolicy 整数 应用程序是否 (0) 具有 (1) 隐私政策。对于此字段,Vungle Exchange 只支持 '1'。
paid 整数 应用程序是否 (0) 已付费 (1)。
keywords 字符串 以逗号分隔的发布人应用程序的标签的列表。
ext 对象 描述

2.4.4 应用程序扩展

字段 类型 必填 描述
altid 字符串 用来唯一识别发布人应用程序的 Vungle Exchange 特定二级 ID;例如,'3a06eb14e67c98f761add01'。
sdk 对象 请参阅 SDK 扩展对象。
wtags 字符串数组 发布人应用程序标签白名单。
btags 字符串数组 发布人应用程序标签黑名单。
bundleid 字符串 应用程序捆绑包识别码或包名称。
tags 字符串数组 已弃用;请使用关键字。

2.4.5 SDK 扩展

字段 类型 必填 描述
name 字符串 标识安装在主应用程序上的 SDK 代理程序的 SDK 系列的字符串。例如,'VungleDroid', 'Vungle', or 'VungleWindows'。
ver 字符串 描述安装在主应用程序上的 SDK 代理程序版本的字符串。
plugin 字符串 使用其构建 SDK 代理程序的 SDK 插件的名称;例如,'native', 'unity'。
pluginver 字符串 使用其构建 SDK 代理程序的 SDK 插件的版本;例如,'1.0'。

2.4.6 发布人对象

字段 类型 必填 描述
id 字符串 Vungle Exchange 生成的发布人 ID,例如,'570ffeb14e67998f761a791c'。
name 字符串 发布人名称;例如,'Supercell Oy'。
cat 字符串数组 请参阅 OpenRTB 2.3.1 第 5.1 部分。

2.4.7 设备对象

字段 类型 必填 描述
ua 字符串 设备浏览器用户代理字符串;例如,'Mozilla/5.0 (iPhone; CPU iPhone OS 9_1 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13B143 Safari/601.1'。
ip 字符串 显示 ipv6 字段时不需要。这是展示的 IP 地址;例如,'212.14.27.104'。
ipv6 字符串 显示 IP 字段时不需要。展示的 IPv6 地址;例如,'3ffe:1900:4545:3:200:f8ff:fe21:67cf'。
h 整数 以像素计的设备屏幕高度。
w 整数 以像素计的设备屏幕宽度。
connectiontype 字符串 请参阅 OpenRTB 2.3.1 第 5.18 部分。
ifa 字符串 支持的供广告客户用于纯文本的 ID;例如,'e4fe9bdecaa047b6908dffba3fa184f2'。
geo 对象 请参阅地理对象。
make 字符串 设备制造。
model 字符串 设备型号。
os 字符串 设备操作系统;例如,'iOS', 'Android'。枚举值:
- 'iOS'
- 'Android'
- 'Windows'
osv 字符串 设备操作系统的版本;例如,'9.1', '8.0'。
dnt 整数 设备是否 (0) 指定 (1)“不跟踪”。
lmt 整数 设备是否 (0) 指定 (1)“有限广告跟踪”。
devicetype 字符串 请参阅 OpenRTB 2.3.1 第 5.17 部分。
language 字符串 以 ISO-639-1-alpha-2 显示的设备语言;例如,'en'。
carrier 字符串 运营商或 ISP;例如,'VERIZON'。
ext 对象 请参阅设备扩展对象。

2.4.8 设备扩展

字段 类型 必填 描述
tz 字符串 在 IANA 时区数据库中使用时区名称作为格式的设备时区设置;例如,'America/Los_Angeles'。
vungleua 字符串 已弃用:请使用 Application.ext.vungle.sdk
sdcard 整数 SD 卡存储是否 (0) 可用于 (1) Android 设备。
volume 浮动 指示设备体积百分比的 0 与 1 之间的值。
muted 整数 0 = false 1 = true;所需枚举。
idfv 字符串

iOS 设备上供应商的 ID;供应用供应商唯一识别设备的字母数字字符串;例如,'00000000-0001-4d3a-8f98-233623cd8d12'。

相同设备可能包含不同的 IDFV 值,具体取决于出价请求中的应用是否属于不同供应商。

marketplace 字符串

安装在设备上的应用商店。可能值为:

  • 'google'
  • 'apple'
  • 'amazon'
is_sideload_enabled 整数 指示设备是否允许从“未知”来源安装应用的布尔标记。如果为 '1' (true),允许来自未知商店的应用。如果为 '0' (false),则不允许。

2.4.9 地理对象

字段 类型 必填 描述
country 字符串 以 ISO-3166-1-alpha-3 显示的国家/地区代码;例如,'USA'。
lat 浮动 设备的纬度;例如,'[-90, 90]'。
long 浮动 设备的经度;例如,'[-180, 180]'。
type 整数 请参阅 OpenRTB 2.3.1 第 5.16 部分。
region 字符串 以 ISO-3166-2 显示的地区代码;如果为美国,则为 2 个字母的国家代码;例如,'CA'。
city 字符串 自由格式的城市名称。
zip 字符串 邮政编码。
utcoffset 整数 以数字 +/- UTC 分钟计算的本地时间。

2.4.10 注册对象

字段 类型 必填 描述
coppa 整数 指示此请求是否须遵守 USA FTC 制定的 COPPA 法规的标记,其中 0 = 否,1 = 是。
ext 对象 OpenRTB 的 Vungle Exchange 特定扩展的占位符。

2.4.11 PMP 对象

字段 类型 必填 描述
private_auction 整数 直接交易对象中指定席位的拍卖资格的指示符,其中 0 = 接受所有出价,1 = 出价被限制为指定交易及其条款。
deal 对象数组 传达适用于此展示的特定交易的交易数组(第 3.2.18 部分)对象。
ext 对象 OpenRTB 的 Vungle Exchange 特定扩展的占位符。

3.响应

3.1 必填字段和可选字段

有关“响应”部分必填列的注释:

  • 是:Vungle Exchange 假设必填字段始终具有指定类型的非空格式;无效值可能导致失去拍卖资格。
  • 建议:如果字段值使用指定格式,Vungle Exchange 将使用该字段协助拍卖过程;缺少字段或字段无效不会对拍卖资格造成负面影响。
  • 否:Vungle Exchange 不需要这些字段。
  • 默认:OpenRTB 2.3.1 中所有未提到的字段默认要求均为 'No'。此外,所有字段均必须具有指定类型,否则可能对拍卖资格造成负面影响。

3.2 响应头

响应头必须包含“内容-类型”头,且具有其中一个上述请求头接受的值。例如,

Content-Type: application/json

3.3 响应状态代码

所有响应均必须为 200 或 204。任何其他 HTTP 响应代码均有可能对 DSP 的拍卖资格造成负面影响。

3.4 无出价原因信号

建议 DSP 在决定不出价时发送无出价原因。此信息可以帮助 Vungle Exchange 检测并修复潜在的集成问题。无出价信号应该遵循 OpenRTB 2.3.1 第 7.4 部分的规范。包含无出价原因的正确格式的无出价信号应看似这样:


{"id": "1234567890", "seatbid": [], "nbr": 2}

3.5 BidResponse 对象

字段 类型 必填 描述
id 字符串 Vungle Exchange 生成的 BidRequest ID;例如,'570ffeb14e67998f761a791c'。此 ID 必须与 BidRequest 对象中的 ID 相同。
bidid 字符串 帮助记录/跟踪的出价人生成的唯一响应 ID。
cur 字符串 使用 ISO-4217 alpha 代码的出价货币。Vungle Exchange 目前只支持 USD,并将任何值都视为 USD。
seatbid 对象数组 seatbid 对象数组;如果进行了出价则需要 1+。
nbr 整数 OpenRTB 2.3.1 规范的 5.19 中列出的未出价原因。
ext 对象  

3.5.1 SeatBid 对象

字段 类型 必填 描述
seat 字符串 代表其出价的出价人席位的 ID。请参阅 OpenRTB 2.3.1
bid 对象数组 请参阅出价对象。必须至少存在一个出价。


3.5.2 出价对象

字段 类型 必填 描述
id 字符串 各个 DSP 生成的出价 ID。
impid 字符串 与为其出价的出价请求的展示有关的展示 ID。必须与出价请求展示对象中的 ID 相同。
price 浮动 以 CPM 单位表示的出价价格;例如,'10.30'。
nurl 字符串 出价胜出时 Vungle Exchange 调用的胜出通知 URL。
adm 字符串 将在赢得拍卖后提供的广告标记。请参阅广告标记规范部分。
cid 字符串 建议 DSP 代理的活动 ID。
crid 字符串 建议 DSP 代理的创意 ID。
adomain 字符串数组 建议 用于阻止列表检查的广告客户域;例如,["supercell.com"]。
bundle 字符串 建议 唯一的市场 ID,这是平台特定的应用程序识别码,对于应用是唯一的,与 Vungle Exchange 无关
- 在 Android 上,这应该是捆绑包或包名称(例如,'com.supercell.hayday')。
- 在 iOS 上,这是一个数字 ID。
h 整数 建议 创意的高度。
w 整数 建议 创意的宽度。
cat 字符串数组 IAB 内容类别;请参阅 OpenRTB 2.3.1 第 5.1 部分。
iurl 字符串 丢失的通知 URL。
dealid 字符串 如果此出价属于私人商店直接交易,则是对 BidRequest 对象的 deal.id 的引用。
adid 字符串 将在出价胜出时提供的预加载广告的 ID。
ext 对象  

4.示例

4.1 请求示例


{
    "id": "58ed309efa8936087efd1349",
    "imp": [{
        "id": "58ed309efa8936087efd134a",
        "video": {
            "mimes": ["video/mp4"],
            "minduration": 5,
            "maxduration": 30,
            "protocols": [2, 5],
            "w": 1080,
            "h": 1920,
            "startdelay": 0,
            "linearity": 1,
            "minbitrate": 250,
            "maxbitrate": 2500,
            "boxingallowed": 1,
            "playbackmethod": [1, 2, 3, 4],
            "delivery": [1, 2],
            "pos": 7
        },
        "displaymanager": "Vungle",
        "displaymanagerver": "3.3.5",
        "instl": 1,
        "bidfloor": 15,
        "bidfloorcur": "USD"
    }],
    "app": {
        "id": "56b8e577819502560b000033",
        "name": "test-pub-app-name",
        "bundle": "1045826890",
        "storeurl": "https://itunes.apple.com/us/app/id1234567?mt=8",
        "cat": [
            "IAB1"
        ],
        "privacypolicy": 1,
        "publisher": {
            "id": "test-pub-app-id",
            "name": "test-pub-app-name",
            "cat": [
                "IAB1"
            ]
        },
        "ext": {
            "vungle": {
                "altid": "5fff577819502560b000033",
                "btags": ["real money gambling", "social casino"],
                "wtags": ["targeted tag", "social"]
            }
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_4 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12H141",
        "geo": {
            "lat": 47.46,
            "lon": -122.16,
            "type": 1,
            "country": "USA",
            "region": "WA",
            "city": "San Francisco",
            "zip": "94103"
        },
        "dnt": 0,
        "lmt": 0,
        "ip": "192.168.1.1",
        "devicetype": 1,
        "make": "Samsung",
        "model": "SM-J200G",
        "connectiontype": 2,
        "os": "iOS",
        "osv": "8.0",
        "w": 1080,
        "h": 1920,
        "js": 1,
        "language": "en",
        "ifa": "test-ifa",
        "ext": {
            "vungle": {
                "isSdCardAvailable": 1,
                "vungleua": "VungleDroid/3.3.5",
                "tz": "Europe/Kaliningrad",
                "sdcard": 1,
                "volume": 0.13333334,
                "muted": 1
            }
        }
    },
    "bcat": ["IAB7-3", "IAB7-5", "IAB7-28", "IAB7-29", "IAB7-30", "IAB7-39", "IAB7-41", "IAB7-42"],
    "at": 2,
    "cur": ["USD"],
    "tmax": 250
}

4.2 响应示例


{
  "id": "58ed309efa8936087efd1349",
  "bidid": "5508",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "7735",
      "bid": [
        {
          "id": "5508",
          "impid": "58ed309efa8936087efd134a",
          "price": 50,
          "nurl": "http://bidder.com/won?price=${AUCTION_PRICE}",
          "adm": "http://bidder.com/vast?id=${AUCTION_ID}",
          "cid": "554d550b418461cc3700014d",
          "crid": "57767c29a63510e75f000073"
        }
      ]
    }
  ]
}

5.广告标记规范

Vungle Exchange 主要支持三类标记:VAST、MRAID 和专有的 Vungle 广告标记。虽然每个标记有其自己的高级规范,但若要被视为能够达到预期效果的有效标记,其还必须符合下列额外要求。

5.1 VAST

以下标签必须出现在 'adm' 字段的前 100 个字节中,或 'nurl' 响应的负载中:

<VAST version="2.0">

5.2 宏替换

Vungle Exchange 在出价响应中支持出价对象 nurl 字段中的拍卖价格的宏替换。例如:


"nurl": "http://bidder.com/won?price=${AUCTION_PRICE}"
还有其它问题?提交请求

评论