|
|
竞价响应
尺寸
竞价响应的最大尺寸为 4KB。
要传送无竞价响应，请发送带有状态代码 204 的空响应。
竞价胜出/失败/计费通知
AppLovin RTB 会在请求的
nurl
、
lurl
和
burl
字段中，分别调用请求方提供竞价胜出、失败和计费通知 URL。竞价完成后，AppLovin RTB 会调用胜出 URL，并将广告发送至设备。失败 URL 会在竞价过程中、相关广告未能正常加载或其他胜出广告加载后调用。当设备渲染广告——即视频广告开始播放或设备展示图像广告时，AppLovin RTB 则会调用计费 URL。
请求方可将宏嵌入上述通知 URL 规格中。在请求 URL 之前，AppLovin RTB 会用合适的值替换 URL 中的宏。请查看下方列表，了解请求方可以在此类 URL 中嵌入哪些宏：
这些宏均区分大小写，在说明宏时请全部用大写。请将这些宏包含在
${…}
中 (例如
${AUCTION_ID}
)。
| 宏 | 描述 |
|---|---|
AUCTION_BID_ID
|
来自
BidResponse.bidid
属性的竞价 ID。
|
AUCTION_ID
|
来自
BidRequest.id
属性的竞价请求 ID。
|
AUCTION_LOSS
|
竞价失败原因代码，请参阅 OpenRTB 2.5 规范
第 5.25 条中的表格
。仅随
lurl
发送。
|
AUCTION_MINIMUM_BID_TO_WIN
|
排名第二高的出价。该值仅对竞价获胜方有意义，如果是通过
lurl
发送的，可以忽略。如果只有一个竞价——即中标竞价，那么发送的值为
0
。
|
AUCTION_PRICE
|
竞价获胜/结算价格 (Auction winning / Clearing price)。此值会同时出现在
nurl
和
lurl
字段中，因此每个竞价方 (无论是否获胜) 都可以看到最终成交价格。该价格使用与出价相同的货币和单位，最多可保留六位小数。若无中标竞价，则传入的值为
0
。
|
带有宏的胜出竞价 URL 示例
https://example.com/endpoint/auction=${AUCTION_ID}&price=${AUCTION_PRICE}广告标记标准
DSP 竞价方必须在竞价响应中包含广告标记。AppLovin RTB 不支持在竞价胜出通知后返回广告标记。
您的广告标记必须符合 AppLovin 的 RTB 广告标记标准。AppLovin RTB 服务器会在收到竞价后立即检查广告标记是否合规，然后对广告标记进行以下合理性检查：
CDATA
结构中。XML 中的
CDATA
不需要任何编码。但是，如果您在 JSON 上下文中传递 XML 文档，那么必须使用如下 JSON 语法和转义规则：
\"
。
要验证广告标记片段及其
CDATA
是否为有效 JSON 内容，您可以将该片段发送至
JSONLint 在线验证工具
。
所有素材均应通过 SDK 渲染，因此 SDK 竞价方无需传递广告标记。SDK 竞价方可以使用
admarkup
字段传递自定义数据，并进行配置，通过适配器在加载时将自定义数据返回至 SDK。
竞价响应组件
竞价响应由 3 个组件组成：
bidresponse
seatbid
竞价响应对象
| 属性 | 类型 | 描述 | 是否必需？ |
|---|---|---|---|
bidid
|
字符串 | 竞价方生成的响应 ID，用于辅助记录/跟踪。 | 否 |
cur
|
字符串 |
当前仅接受且默认为
"USD"
。
|
否 |
id
|
字符串 |
该响应对应的竞价请求 ID (必须与
bidrequest.id
相同)。
|
是 |
nbr
|
整数 | 未竞价的原因。请参阅 OpenRTB 规格 2.5 中 第 5.24 条的列表 了解更多详情。 | 推荐 |
seatbid
|
对象数组 | seatbid 对象 数组。如果要进行竞价，则需要提供一个或多个该对象。 | 是 |
Seatbid 对象
| 属性 | 类型 | 描述 | 是否必需？ |
|---|---|---|---|
bid
|
对象数组 | 竞价对象数组 ；如果要进行竞价，则需要提供一个或多个该对象。 | 是 |
seat
|
字符串 | 该竞价所代表的竞价方席位 ID。竞价响应可能包含来自多个 “席位” 的竞价，或来自同一席位的多个竞价。 必须 为字母数字字符串，最长不超过 40 个字符，最好不少于 8 个字符。当前不支持。 | 否 |
| 属性 | 描述 | 是否必需？ |
|---|---|---|
adid
(字符串)
|
竞价胜出时投放的预加载广告 ID。 | 否 |
adm
(字符串)
|
在竞价胜出时传递广告标签的主要方式。如果两者都包含广告标记，那么优先采用该方法，而非胜出通知。可能包含替换宏。请参阅
受支持的宏
版块，了解更多信息。原生广告格式支持
adm_native
。
|
是 |
adomain
(字符串数组)
|
广告主域名数组。AppLovin RTB 仅使用数组中的第一个域名。广告主域名必须与广告主落地页的顶层域名相同，而
不是
完整落地页 URL。对于 App Store 落地页，
adomain
必须与应用所有者的顶层域名相同，而
不是
完整的应用商店 URL。
adomain
值
不得
包含 “
http://
”、“
https://
” 或任何 “
/
” (斜杠) 字符。示例：
yourapp.com
(
不是
yourapp.com/something
或
https://yourapp.com
)。
|
是 |
api
(整数)
|
请参阅 OpenRTB 规范 2.5 版本 第 5.6 条中的表格 了解详情。 | 否 |
apis
(整数数组)
|
该展示支持的 API 框架列表。可以是以下任一：
|
|
attr
(整数数组)
|
适用时必要。素材属性，来自下表的值数组：
|
推荐 |
bundle
(字符串)
|
广告主的应用程序 iTunes ID 或 Android 包名。如果不是应用程序安装广告，请留白。请勿传递开发者的应用程序 bundle，否则 AppLovin RTB 将拒绝响应。示例：Android 端为
com.example.app
，iOS 端为
628677149
。
|
ext.skadn
存在时为必需；所有场景均推荐
|
burl
(字符串)
|
当中标竞价变为可计费状态时，广告交易平台调用的计费通知 URL。针对展示和支出跟踪，DSP 必须使用
burl
。只有使用
burl
进行跟踪时，AppLovin 才会调查差异。
|
是 |
cat
(字符串数组)
|
素材的 IAB 内容类别。请参阅 OpenRTB 规范 2.5 版本中 第 5.1 条 了解更多详情。 | 是 |
cid
(字符串)
|
帮助检查广告品质的 Campaign ID。以
iurl
为代表的素材组。
|
推荐 |
crid
(字符串)
|
一个 campaign 素材的唯一标识。即便同样的素材会出现在新的展示中，也请勿为相同的素材分配新的素材 ID。 | 是 |
dealid
(字符串)
|
如果该竞价适用广告资源包，则引用该出价请求中的
deal.id
。除非针对广告资源包进行竞价，否则请勿传递该属性。
|
是，针对广告资源包 |
ext
(对象)
|
特定竞价方的 OpenRTB 扩展的占位符。 | 否 |
ext.crtype
(字符串)
|
该字段描述您要投放的广告类型。有效值如下：
crtype
，AppLovin 可以为您硬编码
crtype
。为此，请联系您的 AppLovin 客户经理。也支持在
bid.crtype
中传递
crtype
。
|
推荐 |
ext.clicktrackers
(字符串数组)
|
AppLovin 记录点击事件时要持续跟踪的 (第一方和第三方) 点击跟踪 URL。不适用于原生广告。 | 是，如果投放 HTML 广告 + SKAD (SKAdNetwork)。 |
ext.duration
(整数)
|
视频时长 (以秒计)。 | 是，针对 CTV 库存。 |
ext.imptrackers
(字符串数组)
|
针对第三方跟踪需求的展示跟踪 URL。不适用于原生广告。请参阅
原生对象
eventtrackers
。
|
否 |
ext.skadn
(对象)
|
支持 Apple SKAdNetwork 归因 API 所需的参数，通过
loadProduct()
。
|
否 |
ext.skadn.campaign
(字符串)
|
Campaign ID (2.0–3.0) 或 Source ID (4.0+)。针对 SKAdNetwork 2.0–3.0 版本，应当为 1 - 100 之间的整数；对于 4.0 及以上版本，应当为 0 - 9999 之间以字符串表示的整数。 |
如果
ext.skadn
存在。
|
ext.skadn.fidelities[]
(对象数组)
|
支持 SKAdNetwork v2.2 引入的多种 fidelity-type。 |
如果
ext.skadn
存在。
|
….fidelities[«n»].fidelity
(整数)
|
要跟踪的归因 fidelity-type。 |
如果
ext.skadn
存在。
|
….fidelities[«n»].nonce
(字符串)
|
每个广告响应的唯一 ID。请参阅 Apple 文档，了解 UUID 正确格式要求 。 |
如果
ext.skadn
存在。
|
….fidelities[«n»].signature
(字符串)
|
Apple 指定的 SKAdNetwork 签名。 |
如果
ext.skadn
存在。
|
….fidelities[«n»].timestamp
(字符串)
|
signature
节点使用的 Unix 时间 (以毫秒计) 字符串。
|
如果
ext.skadn
存在。
|
ext.skadn.itunesitem
(字符串)
|
Apple App Store 中广告主应用的 ID。应与
BidResponse.seatbid.bid.bundle
相同。
|
如果
ext.skadn
存在。
|
ext.skadn.network
(字符串)
|
签名中使用的广告平台标识符。应与请求中
skadnetids
数组的条目之一相同。
|
如果
ext.skadn
存在。
|
ext.skadn.nonce
(字符串)
|
每个广告响应的唯一 ID。请参阅 Apple 文档，了解
UUID 正确格式要求
。
提示：
SKAdNetwork v2.2 发布后，该字段已被弃用，改为支持多个 fidelity-type 的
ext.skadn.fidelities[«n»].nonce
。
|
如果
ext.skadn
存在。
|
ext.skadn.productpage
(字符串)
|
自定义产品页 ID。 | 否 |
ext.skadn.signature
(字符串)
|
Apple 指定的 SKAdNetwork 签名。
提示：
SKAdNetwork 2.2 发布后，该字段已被弃用，改为支持多个 fidelity-type 的
ext.skadn.fidelities[«n»].signature
。
|
如果
ext.skadn
存在。
|
ext.skadn.skoverlay
(对象)
|
用于控制潜在 SKOverlay 的参数。SKOverlay 的触发条件 (带延迟；无延迟：
0
)：视频开始播放，伴随广告渲染，或用户关闭叠加层、但广告保持打开状态。
提示：
由于 Apple 不提供点击回传，因此 AppLovin 不会跟踪 SKOverlay 上的点击。
|
否 |
….skoverlay.position
(整数)
|
叠加层的位置。
0
= 底部，
1
= 底部向上 (bottomRaised)。默认为
0
。
|
否 |
….skoverlay.dismissable
(整数)
|
用户是否可以关闭叠加层。
1
：叠加层可以关闭；
0
：叠加层在屏幕上静态显示。默认为
1
。
|
否 |
….skoverlay.video_delay
(整数)
|
视频开始显示叠加层后的时间 (以秒计)。如果设置为
-1
，那么就不会在视频开始时触发。
|
如果
ext.skadn.skoverlay
存在。
|
….skoverlay.companion_delay
(整数)
|
伴随广告渲染并显示叠加层后的时间 (以秒计)。如果设置为
-1
，那么就不会在伴随广告渲染时触发。
|
如果
ext.skadn.skoverlay
存在。
|
….skoverlay.sk_dismiss_delay
(整数)
|
在 StoreKit 界面关闭后、延迟多少秒再显示叠加层 (以秒计)。设置为
-1
，就不会在 StoreKit 关闭时触发。
|
如果
ext.skadn.skoverlay
存在。
|
ext.skadn.sourceapp
(字符串)
|
Apple App Store 中开发者应用的 ID。应与
BidRequest.imp.ext.skad.sourceapp
相同。
|
如果
ext.skadn
存在。
|
ext.skadn.timestamp
(字符串)
|
signature
节点使用的 Unix 时间 (以毫秒计) 字符串。
提示：
SKAdNetwork 2.2 发布后，该字段已被弃用，改为支持多个 fidelity-type 的
ext.skadn.fidelities[«n»].timestamp
。
|
如果
ext.skadn
存在。
|
ext.skadn.version
(字符串)
|
预期的 SKAdNetwork 版本，不得低于 2.0。 |
如果
ext.skadn
存在。
|
ext.vendor
(字符串数组)
|
监测所投放广告可见度的可见度代理商名称。只有在为某次展示收集了可见度监测时，您才应当在竞价响应中声明可见度代理商。针对 Integral Ad Science (IAS) 设为
"ias"
；针对 Moat 设为
"moat"
。在返回可见度相关的展示 campaign 时，买方必须在竞价响应中包含代理商名称。此项不适用于 Open Measurement 可见度。
|
针对监测可见度的 campaign |
h
(整数)
|
素材高度 (以密度无关像素计)。 | 推荐 |
id
(字符串)
|
竞价方生成的竞价 ID，用于辅助记录/跟踪。 | 是 |
impid
(字符串)
|
相关竞价请求中 展示对象 的 ID。 | 是 |
lurl
(字符串)
|
竞价失败通知 URL，由广告交易平台在已知竞价失败时调用。其中可能包含替换宏。请参阅 受支持的宏 版块了解详情。 | 否 |
nurl
(字符串)
|
竞价赢得展示机会时，广告交易平台调用的竞价胜出通知 URL。 | 推荐 |
price
(浮点数)
|
竞价价格以 CPM (每千次展示成本)表示，但实际交易仅用于单次展示。提示：虽然该字段类型指示浮点数，但在处理货币时，我们强烈建议您使用整数运算 (例如 Java 中的
BigDecimal
)。
|
是 |
protocol
(整数)
|
标记的视频响应协议 (如适用)。请参阅 OpenRTB 规格 2.5 第 5.8 条中的表格 了解详情。 | 否 |
w
(整数)
|
素材宽度 (以密度无关像素计)。 | 推荐 |
请参阅下方表格，了解需求方平台可用的跟踪字段及其推荐用途。
bidresponse.bid.
跟踪器
|
方法 | 推荐用途 |
|---|---|---|
.adm
|
|
|
.adm.native.eventtrackers
|
客户端触发 |
img
和
js
标签。详情请参阅
Open RTB 1.2 原生广告规格
第 7.7 条 “Event Tracking Methods Table” (事件跟踪方法表格) 中定义的 “方法”。
native.imptrackers
和
native.jstracker
字段即将被 IAB 弃用，改为
eventtrackers
，因此我们建议 DSP 使用
native.eventtrackers
。
|
.adm.native.imptrackers
|
客户端触发 (已弃用，改为
eventtrackers
)
|
无效流量 (IVT) 跟踪 |
.adm.native.jstracker
|
客户端触发 (已弃用，改为
eventtrackers
)
|
Open Measurement SDK (OMSDK) |
.adm.native.link.clicktrackers
|
客户端触发 | 点击跟踪 (可选) |
.burl
|
服务器端触发。
X-Device-IP
和
X-Device-User-Agent
会在服务器端到服务器端的回传中以标头形式发送：
|
买方 (DSP) 展示和支出跟踪 |
.ext.imptrackers
|
服务器端触发。
X-Device-IP
和
X-Device-User-Agent
会在服务器端到服务器端的回传中以标头形式发送：
|
合作伙伴展示跟踪 |
竞价响应示例
{ "id": "5e1eb292d6b7ea9cf3da74ddb385996a62d3a6e9", "seatbid": [ { "bid": [ { "id": "8JxH4DHN4KMF21Vd", "impid": "1", "price": 15, "adid": "1093919"
, "adm": "<a href=\"https://click.url/click/8JxH4DHN4KMF21Vd?uid=05D02DC6-0132-4C2C-A879-79BB026BE3F8&partner=applovin&ts=2018-07-09T18-19-01Z&ad=1093919\"><img src=\"https://assets.dsp.io/ad_assets/files/320x50.png\" height=\"50\" width=\"320\" alt=\"\"/></a>", "adomain": [ "advertiser.com" ], "bundle": "123123123", "iurl": "https://assets.dsp.io/ad_assets/files/320x50.png", "cid": "12345", "crid": "crid123", "cat": [ "IAB22-2" ], "h": 50, "w": 320, "ext": { "crtype": "HTML", "imptrackers": [ "https://example.dsp.events/win/8JxH4DHN4KMF21Vd?ts=2018-07-09T18-19-01Z&ad=1093919&uid=05D02DC6-0132-4C2C-A879-79BB026BE3F8&auction=${AUCTION_ID}&price=${AUCTION_PRICE}&partner=applovin" ] } } ] } ], "bidid": "8JxH4DHN4KMF21Vd", "cur": "USD"}原生广告响应示例
{ "bidid":"9aa2a2950894c95b9b02476a5ba5438dc6de8dc1", "cur":"USD", "id":"65de6af36e6fb32778afa94a996ec4c2b514145d", "seatbid":[ { "bid":[ { "adm":"{\"native\":{\"assets\":[{\"id\":100,\"title\":{\"text\":\"Test Ad\"}},{\"id\":200},{\"id\":300,\"img\":{\"h\":null,\"url\":\"https://assets.com/main_image.png_\",\"w\":null}},{\"id\":310,\"img\":{\"h\":80,\"url\":\"https://assets.com/icon_image.png\",\"w\":80}},{\"data\":{\"value\":\"Test Ad Subline\"},\"id\":420},{\"data\":{\"value\":\"Continue\"},\"id\":430},{\"data\":{\"value\":\"4.5\"},\"id\":410}],\"imptrackers\":[\"https://adserver.com/impression_tracker\"],\"link\":{\"url\":\"https://adserver.com/click_destination\"}}}\n", "adomain":[ "somegame.com" ], "bundle":"com.game.example", "cat":[ "IAB1" ], "crid":"74650.0!3ILDTypkALKe8xfw2WJLmxfNOftiOg2u3yeGIKEULAU*", "ext": { "crtype":"native" }, "id": "1", "impid": "1", "iurl": "https://assets.com/preview.png", "price": 1.0 } ], "seat":"A00000001" } ]}