广告返回

Read time 27 minutes

对于广告返回数据，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 对象
seatbid 对象

一种包含 bid 对象数组（允许合作伙伴代表多个帐户进行出价）的对象类。

属性类型示例描述
bid
对象数组

如需了解更多信息，请参阅有关 bid 对象 的部分。

一个或多个出价。进行多个出价时，请包含最高出价以最大化地增加赢得广告竞价的几率。

seat
字符串
"seat":"1234"

买家席位的 ID，或委托您代表出价的广告主或代理商。

bid 对象
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.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 响应
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)
无广告返回 (NBR)

对于无出价，Unity Exchange 支持多种响应类型。使用如下任意一种响应类型来明确表示您希望不进行出价，这对于我们来说很重要，否则该响应可能会被认为是超时错误。

响应示例
无内容
HTTP 204 No Content
空 JSON 对象
{}
格式正确的广告返回（带有或不带有原因代码）
{"id":"1234567890", "seatbid": {}, "nbr":2}
其他
  • 200 OK
  • 302 Redirect

如需了解更多信息，请参阅 OpenRTB 规范的第 7.1 节。

NBR 原因代码
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))