文档

支持

Unity Exchange

Get started with Unity Exchange

Bid requests

Creative format guidelines

Unity Exchange

广告返回

Help demand partners structure valid responses that meet auction and ad delivery requirements.
阅读时间 11 分钟最后更新 3 days ago
对于广告返回数据，Unity 支持 JSON 格式。标准 JSON 表示法的 MIME 类型为 
application/json
，并在 
HTTP
标头字段中指定为： 
contentType: application/json
应用程序收到对其专用终端的广告请求后，应用程序必须在 200 毫秒之内发出广告返回或回应不出价。Unity 在广告请求中发送 Accept-Encoding GZIP 压缩数据时，推荐的最佳做法是广告主返回压缩格式的广告填充。如需了解更多信息，请参阅 OpenRTB 规范的第 2.4 节。 以下部分将详细介绍响应对象及其属性。描述字段指出了必需的属性。推荐的最佳做法是包含上所有属性。

响应对象

一种描述出价者对 广告请求 的响应的对象类。

属性

类型

示例

描述

id
字符串
"id":"7jrUifdKuw3HDIR9dbqDVJ"
Unity 生成的 ID，随广告请求一起传递，需要随广告返回一起发回。
cur
字符串
"cur":"USD"
使用 ISO 货币代码表示的货币类型。Unity 支持美元 (
USD
) 以及其他货币（如 
CNY
）。确保此字段与 
adsource
配置中定义的货币字段匹配，并且 
exchange_rate
不为空，否则 Unity 将忽略该广告返回。
bidid
字符串
"bidid":"CHYr9b0ODI8OGLpedtfCpuCH"
出价者生成的响应 ID，有助于进行记录和追踪。
nbr
整型
"nbr":6
拒绝出价的原因。如需查看支持值的完整列表，请参阅 无广告返回的部分。
seatbid
对象数组
如需了解更多信息，请参阅有关 
seatbid
对象的部分。
Unity Exchange 允许在一个响应中存在多个 
seatbid
对象，但目前仅仅只会使用一个 
seatbid
对象数组。选择的 seatbid 对象包含一个等于 
impression.id
的 
bid.id
。如果多个 
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 会忽略等于或小于零的值或加密的值。
adid
字符串
"adid":"12345678"
出价获胜时由出价者生成的待投放预加载广告 ID。
nurl
字符串
"nurl":"https://bidder.com/win?${AUCTION_PRICE}"
当竞价成功时，Unity 会触发该获胜通知 URL。此属性也可用于统计可付费的广告展示（依具体对接情况而定）。Unity 会在展示广告时触发 
nURL
，并用实际的中标价格替换出价宏 (
${AUCTION_PRICE}
)。
burl
字符串
"burl": "https://fake-test.com/imp?${AUCTION_PRICE}"
当中标出价可计费时，由 Unity Exchange 调用的计费通知 URL。该操作基于广告交易平台特有的业务政策。可包括替换宏。Unity 会在展示广告时触发 
bURL
，并用实际的中标价格替换出价宏 (
${AUCTION_PRICE}
)。
iurl
字符串
"iurl": "https://secure-datacenter.dsp.com/cr?id=12345678"
连接到代表广告系列内容图片（用于广告质量和安全性检查）的 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
字符串数组
正确：
  • "adomain": ["yourgame.com"]
  • "adomain": ["studio.yourgame.com"]
错误：
  • "adomain": ["yourgame.com/something"]
  • "adomain": ["www.yourgame.com"]
广告主域名，用于检查屏蔽列表。广告素材不可轮换，并且只允许一个域名。格式必须仅是根域名，不含协议（请注意，如果不是"www"，则可以包括子域名）。
bundle
字符串
Google 示例：
  • "bundle": "com.unityexample.game"
Apple 示例：
  • "1198634425"
平台特定的应用程序标识符（Apple App Store 或 Google Play 的 Store ID），是应用程序唯一的标识，且与广告交易平台无关。此功能也可用于广告质量检查。
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
对象的对象子类。 为了在 iOS14 中支持 SKAdNetwork，您必须将 ext 属性添加为对象。

属性

类型

示例

描述

appid
字符串
"appid":"1234567890123"
推广应用的 App Store ID（如果适用）。如需进一步了解如何查找 App Store ID，请参阅 Unity Ads Monetization（变现）后台文档中有关 Store ID 的内容。
appname
字符串
"appname":"Example Game"
推广的应用程序的应用名称（如果适用）。
storeurl
字符串
"storeurl": "https://itunes.apple.com/us/app/trash-dash/id1198634425?mt=8"
推广的应用程序的 App Store URL（如果适用）。
imptrackers
字符串数组
"https://ad.doubleclick.net/ddm/trackimp", "https://dsp.com/amet?et=show&id=60e47b64b59Q"
一系列广告展示追踪器（用于第一方和第三方），在 Unity 记录可计费广告展示事件时做同步追踪。可用于代替 
bURL
。
length
整型
"length":15
以秒为单位的视频长度（如果适用）。
crtype
字符串
"crtype":"VAST 3.0"
广告资源的广告素材类型。以下类型有效：
  • VAST
  • VAST 2.0
  • VAST 3.0
  • VAST 4.0
  • VAST VPAID
  • MRAID playable
  • MRAID 2.0
  • BANNER
  • HTML
  • HTML5
  • JS
ext.skadn.skoverlay.show
整数
1
指示是否显示 SKOverlay。
  • 1
    表示是。
  • 0
    表示否。
ext.skadn.skoverlay.position
整数
1
指示 SKOverlay 的位置。
  • 0
    表示底部。
  • 1
    表示底部凸起。
  • 默认值为 0。
ext.skadn.skoverlay.dismissable
整数
1
指示用户是否可以关闭 SKOverlay。
  • 0
    表示否（静态）。
  • 1
    表示是（可关闭）。
  • 默认值为 1。
ext.skadn.skoverlay.video_delay
整数
1
指示显示 SKOverlay 前的延迟时间（以秒为单位），0 表示立即显示。
  • 默认值为 5，最大值为 60。
ext.skadn.productpageid
字符串
00d00d1e-ff93-67fc-653f-8ggd1eeghcdf
请参阅 Apple 的 配置多个产品页面版本，以了解更多信息。
ext.skadn.ext.ask
整数
1
表示不同版本的 Auto Storekit。
  • 1
    表示当用户跳过视频广告时显示 Storekit。通过点击跳过按钮而打开 Storekit 时不会发送点击事件。
  • 2
    表示当用户跳过视频广告或结束观看视频广告时显示 Storekit。通过点击跳过按钮而打开 Storekit 时不会发送点击事件。
  • 3
    表示当用户跳过视频广告时显示 Storekit。通过点击跳过按钮而打开 Storekit 时，将发送点击事件。
  • 4
    表示当用户跳过视频广告或结束观看视频广告时显示 Storekit。通过跳过操作打开 Storekit 时，将发送点击事件。
ext.clickablevideo
整数
1
指示是否启用全屏可点的产品体验。
  • 1
    表示是。
  • 0
    表示否。

广告返回示例

试玩广告响应

{ 
  "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;\"></a>\n<script type=\"application/javascript\"> bmTrackViewableChange=function(e){mraid.addEventListener(\"viewableChange\",funct{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 No Content
空 JSON 对象
{}
格式正确的广告返回（带有或不带有原因代码）
{"id":"1234567890", "seatbid": {}, "nbr":2}
其他
  • 200 OK
  • 302 Redirect
如需了解更多信息，请参阅 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))

参数

示例值

key
"encryption_key"
plaintext
"10.20"
encrypted, base64 URL encoded
"z5eznndAkpE="

解密

要解密数据，对输入字符串应进行 base64 URL 解码。然后，从加密的数据中移除 PKCS5 填充，再逆向处理 Blowfish ECB 加密。 伪代码示例 
blowfish_ecb_decrypt_pkcs5_padding(base64_URLDecode(encodedtext))