出价响应
Unity 支持使用 JSON 格式的出价响应数据。标准 JSON 表示的 MIME 类型为 application/json
,并指定在 HTTP
标头字段中为
contentType: application/json
您的应用程序在收到出价请求后,必须在最长 200 毫秒内将其传送到指定的端点,并返回出价响应或表明不出价。Unity 在请求中发送 Accept-Encoding GZIP 压缩,建议最佳实践是压缩响应。有关更多信息,请参阅OpenRTB 规范的第 2.4 节。
Note: The recommended best practice is that DSP servers, including load balancers, activate HTTP Persistent Connections, also known as Keep-Alive, and prevent automatic IdleConnTimeout
for at least 90 seconds. This has a profound impact on overall performance by reducing connection management overhead and CPU utilization on both sides of the interface.
响应对象及其属性在下一节中详细说明。描述字段表示必需的属性。建议最佳做法是包含所有属性。
响应对象
一个对象类,描述竞标者对出价请求的响应。
属性 | 类型 | 示例 | 描述 |
---|---|---|---|
id | 字符串 | "id":"7jrUifdKuw3HDIR9dbqDVJ" | 由 Unity 生成的 ID,随出价请求传递并随出价响应返回。 重要:此属性是响应中的必需属性。 |
cur | 字符串 | "cur": "USD" | 货币类型,使用 ISO 货币代码。Unity 支持美元 ( 重要:此属性是响应中的必需属性。 |
bidid | 字符串 | "bidid": “CHYr9b0ODI8OGLpedtfCpuCH” | 竞标者生成的响应 ID,用于帮助进行日志记录和跟踪。 |
nbr | 整数 | "nbr": 6 | 拒绝出价的原因。有关支持值的完整列表,请参阅OpenRTB API 指南中的表 5.24。另请参阅有关不出价响应部分。 |
seatbid | 对象数组 | 有关更多信息,请参阅有关seatbid 对象的部分。 | Unity Exchange 允许响应中包含多个 重要:此属性是响应中的必需属性。 |
seatbid 对象
一个对象类,包含一个bid
对象数组,允许合作伙伴代表多个账户出价。
属性 | 类型 | 示例 | 描述 |
---|---|---|---|
bid | 对象数组 | 有关更多信息,请参阅有关bid 对象的部分。 | 一个或多个出价。在进行多个出价时,请包含您最高报价,以最大限度地提高赢得拍卖的机会。 重要:此属性是响应中的必需属性。 |
seat | 字符串 | "seat": "1234" | 买方席位 ID,即您代表其出价的广告主或代理商。 重要:此属性是响应中的必需属性。 |
bid 对象
一个对象类,包含有关买方出价的信息。
属性 | 类型 | 示例 | 描述 |
---|---|---|---|
id | 字符串 | "bidid": "1234567890123456789" | 竞标者生成的出价 ID,用于帮助进行日志记录和跟踪。 重要:此属性是响应中的必需属性。 |
impid | 字符串 | "impid": "1" | 与该出价关联的展示 ID。此值与出价请求中提供的展示 ID 相匹配。 重要:此属性是响应中的必需属性。 |
price | 浮点数 | "price": 0.78 | 每次千次展示成本 (CPM) 的出价。Unity Exchange 会忽略等于或小于零的值,或加密的值。 重要:此属性是响应中的必需属性。 注意:Unity 接受最多三位小数,但首选两位。 |
adid | 字符串 | "adid": "12345678" | 竞标者生成的预加载广告 ID,如果出价获胜,将使用该 ID 进行投放。 |
nurl | 字符串 | “nurl”:"https://bidder.com/win?${AUCTION_PRICE}" | 广告渲染给用户后,Unity 会 ping 的获胜通知 URL。此属性还用作计费展示计数器。 注意:Unity 在投放时会触发 nURL ,并将出价价格宏 (${AUCTION_PRICE} ) 替换为出价的实际价格。重要:当响应中没有 bURL 时,此属性是 Unity Exchange 的唯一要求。 |
burl | 字符串 | "burl": "https://fake-test.com/imp?${AUCTION_PRICE}" | 赢得的出价可计费后,Unity Exchange 会调用的计费通知 URL。这基于特定于交易所的业务策略。可以包含替换宏。 重要:当响应中没有 imptrackers 属性时,此属性是 Unity Exchange 的唯一要求。注意:Unity 在投放时会 ping bURL ,并将出价价格宏 (${AUCTION_PRICE} ) 替换为出价的实际价格。 |
iurl | 字符串 | "iurl": "https://secure-datacenter.dsp.com/cr?id=12345678" | 指向代表广告活动内容的图像的 URL,该 URL 没有缓存清除功能(用于广告质量和安全检查)。 |
cid | 字符串 | "cid": "1234" | 竞标者生成的广告活动 ID,用于帮助进行广告质量检查。iURL 图像应代表此内容集合。 |
crid | 字符串 | "crid": "12345678" | 合作伙伴提供的创意 ID,用于帮助进行广告质量检查。 |
dealid | 字符串 | "dealid": "Unity-MM-0034" | 直接交易的唯一标识符(如果适用)。 注意:此 ID 必须与出价请求中发送的交易 ID相匹配。 |
cat | 字符串数组 | "cat": ["IAB3-12", "IAB21-2", "IAB10-9" "NEX3-102"] | 适用于创意的 IAB 内容类别。有关支持值的完整列表,请参阅OpenRTB API 指南中的表 5.1。 重要:此属性是响应中的必需属性。 |
adm | 字符串 | 有关更多示例,请参阅示例出价响应部分。 | 在出价获胜的情况下传达广告标记的方式。 重要:此属性是响应中的必需属性。 |
adomain | 字符串数组 | 正确
不正确
| 广告主域名,用于黑名单检查。创意不可轮播,并且仅允许一个域名。格式必须仅为根域名,不含协议(请注意,如果子域名不是“www”,则可以包含它们)。 重要:此属性是响应中的必需属性。 |
bundle | 字符串 | Google 示例
Apple 示例
| 平台特定的应用程序标识符(Apple App Store 或 Google Play 的商店 ID),该标识符对于所宣传的应用程序是唯一的,并且独立于交易所。此功能还可用于广告质量。 重要:此属性是针对应用广告的 Unity Exchange 的唯一要求。 |
attr | 整数数组 | "attr": [1, 13] | 描述创意的属性数组。有关支持值的完整列表,请参阅OpenRTB API 指南中的表 5.3。 |
w | 整数 | "h": 568 | 创意的宽度(以设备无关像素 (DIPS) 为单位)。 重要:此属性是横幅广告的必需属性,建议所有格式都使用此属性。 |
h | 整数 | "w": 320 | 创意的高度(以设备无关像素 (DIPS) 为单位)。 重要:此属性是横幅广告的必需属性,建议所有格式都使用此属性。 |
api | 整数 | "api":7 | 此展示支持的 API 框架。值为 7 表示支持 Open Measurement (OM)。有关更多信息,请参阅有关OM 扩展的文档。 |
bid.ext 对象
一个扩展 bid
对象的对象子类。
重要:您必须将 ext 属性添加为对象,以使用 iOS14 的 SKAdNetwork。
属性 | 类型 | 示例 | 描述 |
---|---|---|---|
appid | 字符串 | "appid": "1234567890123" | 要宣传的应用的应用商店 ID(如果适用)。有关查找应用商店 ID 的更多信息,请参阅 Unity Ads 变现控制面板文档中的商店 ID部分。 |
appname | 字符串 | "appname": "Example Game" | 要宣传的应用的应用名称(如果适用)。 |
storeurl | 字符串 | "storeurl": "https://itunes.apple.com/us/app/trash-dash/id1198634425?mt=8" | 要宣传的应用的应用商店 URL(如果适用)。 重要:此属性是针对应用广告的 Unity Exchange 的唯一要求。 |
imptrackers | 字符串数组 | ["https://ad.doubleclick.net/ddm/trackimp", | 展示跟踪器(第一方和第三方)的数组,在 Unity 记录可计费展示事件时始终对其进行跟踪。可用于替代出价 bURL 。重要:当响应中没有 burl 属性时,此属性是 Unity Exchange 的唯一要求。 |
length | 整数 | "length": 15 | 视频的长度(以秒为单位)(如果适用)。 |
crtype | 字符串 | "crtype": "VAST 3.0" | 广告素材的创意类型。以下类型有效
重要:这些值不区分大小写。此属性是响应中的必需属性。 |
ext.skadn.skoverlay.show | 整数 | 1 | 指示是否显示 SKOverlay。
重要:如果 show = 1 且其他属性为空,Unity 将显示默认值。 |
ext.skadn.skoverlay.position | 整数 | 1 | 指示 SKOverlay 的位置。
|
ext.skadn.skoverlay.dismissable | 整数 | 1 | 指示用户是否可以关闭 SKOverlay。
|
ext.skadn.skoverlay.video_delay | 整数 | 1 | 指示显示 SKOverlay 之前的延迟时间(以秒为单位),其中 0 表示立即显示。
|
ext.skadn.productpageid | 字符串 | 00d00d1e-ff93-67fc-653f-8ggd1eeghcdf | 有关更多信息,请参阅 Apple 的配置多个产品页面版本。 |
ext.skadn.ext.ask | 整数 | 1 | 表示 Auto Storekit 的不同版本。
|
ext.clickablevideo | 整数 | 1 | 表示是否启用可点击视频体验。
|
示例出价响应
可玩响应
{
"id": "7jrUifdKuw3HDIR9dbqDVJ",
"seatbid": [{
"bid": [{
"id": "1234567890123456789",
"impid": "1",
"price": 0.78,
"adid": "12345678",
"nurl": "https://secure-datacenter.dsp.com/ab?e=wqT_3FL5gUgASotCQAAAQZjkxNjQ.\\u0026referrer=play.google.com%2Fstore%2Fapps%2Fdetails%3Fid%3Dcom.any.game\\u0026pp=${AUCTION_PRICE}\\u0026label=nurl",
"burl": "https://secure-datacenter.dsp.com/ab?e=wqT_3FL5gUgASotCQAAAQZjkxNjQ.\\u0026referrer=play.google.com%2Fstore%2Fapps%2Fdetails%3Fid%3Dcom.any.game\\u0026pp=${AUCTION_PRICE}\\u0026pplabel=burl",
"adm": "<img src=\"https://my.impression.com/custom/pixel?1234%3D\" style=\"display: none;\">\n <a href=\"https:/my.custom.click/event?&partner=myDSP\"><div style=\"position: fixed; top:0; left:0; width: 100vw; height: 100vh; background-position: center center; background-image: url('https://ex_assets.com/ad_assets/files/000/897/403/original/.jpg?c=1595511733'); background-size: contain;\"></div></a>\n<script type=\"application/javascript\"> bmTrackViewableChange=function(e){mraid.addEventListener(\"viewableChange\",function(){console.log(\"empty viewableChange.....event\")}),e&&bmSendImpression()},bmSubscribeViewableEvent=function(){bmSendFill(),bmSubscribeClickEvent(),mraid.addEventListener(\"ready\",function(){console.log(\"empty ready event\")}),mraid.isViewable()?bmSendImpression():(mraid.addEventListener(\"viewableChange\",function(){}),mraid.addEventListener(\"viewableChange\",bmTrackViewableChange))},bmSubscribeClickEvent=function(){window.addEventListener(\"click\",function(e){bmSendClick()},!1)};bmAddContextToUrl(),\"loading\"===mraid.getState()?(mraid.addEventListener(\"ready\",function(){}),mraid.addEventListener(\"ready\",bmSubscribeViewableEvent)):bmSubscribeViewableEvent();\n</script>",
"adomain": ["viaplay.fi"],
"bundle": "com.unityexample.game",
"iurl": "https://secure-datacenter.dsp.com/cr?id=12345678",
"cid": "1234",
"crid": "12345678",
"cat": ["IAB3-12", "IAB3-8", "IAB21-2", "IAB10-9", "IAB3", "NEX3-101", "IAB3-11", "IAB3-10", "NEX3-102", "IAB3-5", "IAB3-6"],
"attr": [],
"h": 320,
"w": 480,
"appcategory": ["Games"],
"appsubcategory": ["Adventure", "Action"],
"ext": {
"appname": "Example Game",
"storeurl": "https://play.google.com/store/apps/details?id=com.unityexample.game",
"crtype": "PLAYABLE"
}
}],
"seat": "1234"
}],
"bidid": "CHYr9b0ODI8OGLpedtfCpuCH",
"cur": "USD",
}
VAST 响应
{
"id": "7jrUifdKuw3HDIR9dbqDVJ",
"bidid": "CHYr9b0ODI8OGLpedtfCpuCH",
"cur": "USD",
"seatbid": [{
"seat": "Example Partner",
"bid": [{
"impid": "1",
"adomain": ["examplegame.com"],
"iurl": "https://secure-datacenter.dsp.com/cr?id=12345678",
"crid": "12345678",
"cid": "1234",
"adid": "87654321",
"cat": ["IAB9-25", "IAB9-25"],
"bundle": "com.unityexample.game",
"attr": [],
"h": 568,
"w": 320,
"id": "unrtb-com.unityexample.game-320x568-1ADJE5D8721B3-453S-9DYA-B0AVD69AA1A1",
"price": 15.04,
"nurl": "https://secure-datacenter.dsp.com/ab?e=wqT_3FL5gUgASotCQAAAQZjkxNjQ.\\u0026referrer=play.google.com%2Fstore%2Fapps%2Fdetails%3Fid%3Dcom.any.game\\u0026pp=${AUCTION_PRICE}\\u0026label=nurl",
"burl": "https://secure-datacenter.dsp.com/ab?e=wqT_3FL5gUgASotCQAAAQZjkxNjQ.\\u0026referrer=play.google.com%2Fstore%2Fapps%2Fdetails%3Fid%3Dcom.any.game\\u0026pp=${AUCTION_PRICE}\\u0026pplabel=burl",
"adm": "<?xml version=\"1.0\"?><VAST version=\"2.0\"><Ad id=\"179e7ee9\"><InLine><AdSystem>yourdsp</AdSystem><Error><![CDATA[https://ads.yourdsp.com/ads/vast.php?appkey=unrtb-com.catchall.game-320x568&adid=179e7ee9&appid=1139609950&aid=1ABAE8D8-21B3-453D-9DEA-B9ABD69AA1A1&partnerkey=unrtb&campaignID=123184311&adgroupID=180968&ra=&code=err]]></Error><Impression><![CDATA[https://ads.yourdsp.com/ads/vast.php?appkey=unrtb-com.catchall.game-320x568&adid=179e7ee9&appid=1139609950&aid=1ABAE8D8-21B3-453D-9DEA-B9ABD69AA1A1&partnerkey=unrtb&campaignID=1234567890&adgroupID=180968&ra=&code=impression]]></Impression><Creatives><Creative AdID=\"179e7ee9\"><Linear><Duration>00:00:15</Duration><TrackingEvents><Tracking event=\"skip\"><![CDATA[https://ads.yourdsp.com/ads/vast.php?appkey=unrtb-com.catchall.game-320x568&adid=179e7ee9&appid=1139609950&aid=1ABAE8D8-21B3-453D-9DEA-B9ABD69AA1A1&partnerkey=unrtb&campaignID=123456789&adgroupID=180968&ra=&code=skip&s=]]></Tracking><Tracking event=\"engagedView\"><![CDATA[https://ads.yourdsp.com/ads/vast.php?appkey=unrtb-com.catchall.game-320x568&adid=179e7ee9&appid=1139609950&aid=1ABAE8D8-21B3-453D-9DEA-B9ABD69AA1A1&partnerkey=unrtb&campaignID=123456789&adgroupID=180968&ra=&code=engagedView&s=]]></Tracking><Tracking event=\"creativeView\"><![CDATA[https://ads.yourdsp.com/ads/vast.php?appkey=unrtb-com.catchall.game-320x568&adid=179e7ee9&appid=1139609950&aid=1ABAE8D8-21B3-453D-9DEA-B9ABD69AA1A1&partnerkey=unrtb&campaignID=123184311&adgroupID=180968&ra=&code=creativeView&s=]]></Tracking><Tracking event=\"start\"><![CDATA[https://ads.yourdsp.com/ads/vast.php?appkey=unrtb-com.catchall.game-320x568&adid=179e7ee9&appid=1139609950&aid=1ABAE8D8-21B3-453D-9DEA-B9ABD69AA1A1&partnerkey=unrtb&campaignID=123184311&adgroupID=180968&ra=&code=start&s=]]></Tracking><Tracking event=\"firstQuartile\"><![CDATA[https://ads.yourdsp.com/ads/vast.php?appkey=unrtb-com.catchall.game-320x568&adid=179e7ee9&appid=1139609950&aid=1ABAE8D8-21B3-453D-9DEA-B9ABD69AA1A1&partnerkey=unrtb&campaignID=123184311&adgroupID=180968&ra=&code=firstQuartile&s=]]></Tracking><Tracking event=\"midpoint\"><![CDATA[https://ads.yourdsp.com/ads/vast.php?appkey=unrtb-com.catchall.game-320x568&adid=179e7ee9&appid=1139609950&aid=1ABAE8D8-21B3-453D-9DEA-B9ABD69AA1A1&partnerkey=unrtb&campaignID=123184311&adgroupID=180968&ra=&code=midpoint&s=]]></Tracking><Tracking event=\"thirdQuartile\"><![CDATA[https://ads.yourdsp.com/ads/vast.php?appkey=unrtb-com.catchall.game-320x568&adid=179e7ee9&appid=1139609950&aid=1ABAE8D8-21B3-453D-9DEA-B9ABD69AA1A1&partnerkey=unrtb&campaignID=123184311&adgroupID=180968&ra=&code=thirdQuartile&s=]]></Tracking><Tracking event=\"complete\"><![CDATA[https://ads.yourdsp.com/ads/vast.php?appkey=unrtb-com.catchall.game-320x568&adid=179e7ee9&appid=1139609950&aid=1ABAE8D8-21B3-453D-9DEA-B9ABD69AA1A1&partnerkey=unrtb&campaignID=123184311&adgroupID=180968&ra=&code=complete&s=]]></Tracking></TrackingEvents><VideoClicks><ClickThrough><![CDATA[https://c.yourdsp.com/ads/c.php?a=unrtb&b=unrtb-com.catchall.game-320x568&c=179e7ee9&d=1ABAE8D8-21B3-453D-9DEA-B9ABD69AA1A1&ct=0&nb=0&its=1499375139&gf=https%3A%2F%2Fcdngs.yourdsp.com%2F1028%2F768x1024_Unsub_NewGame_Video_All_ZHCN_MZCA02xbqA4.ipad_20170629_09_44_11_.mp4&f=&ra=&aid=1ABAE8D8-21B3-453D-9DEA-B9ABD69AA1A1&campaignID=123184311&adgroupID=180968&adgroup=NewGame_iOS_NL&defcpa=0&defcpc=0&appid=1186994231&creativeID=329c8ef3&adType=5&countrycode=NL&ccimpid=X96142d9408c8a40179e7ee907061405&accountid=1028&siteaccountid=4917655231945&pubappid=&sg=&it=&inf=0&price=0.04800847457627119&cg=New,Set&creativeID=329c8ef3]]></ClickThrough><ClickTracking><![CDATA[https://ads.yourdsp.com/ads/vast.php?appkey=unrtb-com.catchall.game-320x568&adid=179e7ee9&appid=1139609950&aid=1ABAE8D8-21B3-453D-9DEA-B9ABD69AA1A1&partnerkey=unrtb&campaignID=123184311&adgroupID=180968&ra=&code=click]]></ClickTracking></VideoClicks><MediaFiles><MediaFile delivery=\"progressive\" type=\"video/mp4\" bitrate=\"500\" width=\"768\" height=\"1024\" scalable=\"true\" maintainAspectRatio=\"true\"><![CDATA[https://cdngs.yourdsp.com/1028/768x1024_Unsub_NewGame_Video_All_ZHCN_MZCA02xbqA4.ipad_20170629_09_44_11_.mp4]]></MediaFile></MediaFiles></Linear></Creative><Creative AdID=\"179e7ee9\"><CompanionAds><Companion width=\"768\" height=\"1024\"><StaticResource creativeType=\"image/jpeg\"><![CDATA[]]></StaticResource><TrackingEvents><Tracking event=\"creativeView\"><![CDATA[https://ads.yourdsp.com/ads/vast.php?appkey=unrtb-com.catchall.game-320x568&adid=179e7ee9&appid=1139609950&aid=1ABAE8D8-21B3-453D-9DEA-B9ABD69AA1A1&partnerkey=unrtb&campaignID=123184311&adgroupID=180968&ra=&code=engagedView]]></Tracking></TrackingEvents><CompanionClickThrough><![CDATA[https://c.yourdsp.com/ads/c.php?a=unrtb&b=unrtb-com.catchall.game-320x568&c=179e7ee9&d=1ABAE8D8-21B3-453D-9DEA-B9ABD69AA1A1&ct=0&nb=0&its=1499375139&gf=https%3A%2F%2Fcdngs.yourdsp.com%2F1028%2F768x1024_Unsub_NewGame_Video_All_ZHCN_MZCA02xbqA4.ipad_20170629_09_44_11_.mp4&f=&ra=&aid=1ABAE8D8-21B3-453D-9DEA-B9ABD69AA1A1&campaignID=123184311&adgroupID=180968&adgroup=NewGame_iOS_NL&defcpa=0&defcpc=0&appid=1186994231&creativeID=329c8ef3&adType=5&countrycode=NL&ccimpid=X96142d9408c8a40179e7ee907061405&accountid=1028&siteaccountid=4917655231945&pubappid=&sg=&it=&inf=0&price=0.04800847457627119&cg=New,Set&creativeID=329c8ef3]]></CompanionClickThrough></Companion></CompanionAds></Creative></Creatives></InLine></Ad></VAST>",
"ext": {
"advertisername": "One Cool Advertiser",
"appid": "1234567890123",
"appname": "Example Game",
"storeurl": "https://itunes.apple.com/us/app/trash-dash/id1198634425?mt=8",
"length": 15,
"crtype": "VAST"
"clickablevideo": 1,
"deeplinking": 1,
"cta_text": "Shop Now",
"skadn": {
"ext": {
"ask": 2
},
"productpageid”: "00d00d1e-ff93-67fc-653f-8ggd1eeghcdf",
"skoverlay”: {
"show”: 1,
"position”: 0,
"dismissable”: 0,
"video_delay”: 5,
}
}
}
}]
}]
}
无出价响应 (NBR)
Unity Exchange 支持多种无出价响应类型。使用其中一种响应明确表示你不想对展示出价很重要,否则响应可能会被解释为超时错误。
响应 | 示例 |
---|---|
无内容 | HTTP 204 无内容 |
空 JSON 对象 | {} |
格式良好的出价响应(有或没有原因代码) | {"id": “1234567890”, “seatbid”: {}, “nbr”: 2} |
其他 |
|
有关更多信息,请参阅 OpenRTB 规范 的**第 7.1 节**。
NBR 原因代码
值 | 描述 |
---|---|
0 | 未知错误 |
1 | 技术错误 |
2 | 无效请求 |
3 | 已知网络蜘蛛 |
4 | 疑似非人为流量 |
5 | 云、数据中心或代理 IP |
6 | 不支持的设备 |
7 | 阻止的发布商或网站 |
8 | 不匹配的用户 |
价格混淆
在发送 nURL
时,建议的最佳做法是在客户端实施对 ${AUCTION_PRICE:BF}
值的混淆,以保护敏感的价格信息。这是一个可选功能。
方法
为了混淆数据,Unity 使用 ECB 模式的 Blowfish,并对输入数据应用 PKCS5 填充(使用 8 字节块大小的 PKCS7 填充)。然后对数据进行 base64 URL 编码,以便二进制数据在 URL 中有效。源代码可应要求提供,以进行故障排除。
示例伪代码
base64_URLEncode(blowfish_ecb_encrypt_pkcs5_padding(plaintext))
参数 | 示例值 |
---|---|
密钥 | "encryption_key" |
明文 | "10.20" |
加密的,base64 URL 编码 | "z5eznndAkpE=" |
Note: Unity uses a different encryption key in live production.
解密
要解密数据,输入字符串将被 base64 URL 解码。然后从加密数据中删除 PKCS5 填充,然后反转 Blowfish ECB 加密。
示例伪代码
blowfish_ecb_decrypt_pkcs5_padding(base64_URLDecode(encodedtext))