广告请求
Enable demand partners to interpret and respond to auction signals effectively.
当 Unity 收到广告请求时,SDK 会将广告请求发送给所有潜在的出价者,包括在用户不限制数据用途的情况下用于个性化广告的数据(请参阅有关数据隐私的文档)。
对于广告请求数据,Unity 支持 JSON 格式。标准 JSON 表示法的 MIME 类型为 ,并在 HTTP 标头字段中指定为:
contentType: application/jsonAccept-Encoding: gzip
Unity 在请求中发送 Accept-Encoding GZIP 压缩数据,并强烈建议对响应进行压缩。如需了解更多信息,请参阅 OpenRTB 规范的第 2.4 节。
注意
除非描述列中另有说明,否则 Unity 会传递以下每个广告请求属性(如果可用)。
请求对象
顶级广告请求对象包含全局唯一的广告请求 ID。
属性 | 类型 | 示例 | 描述 |
|---|
| 字符串 | "id": "bcaIDT1Nbv0zU8mn9tXQ6j"
| Unity 生成的 ID。此 ID 必须在广告返回对象中返回。 |
| 对象 | 如需了解更多信息,请参阅有关 的部分。 | 对于每个广告请求,Unity 支持一个 对象。 |
| 对象 | 如需了解更多信息,请参阅有关 的部分。 | 私有市场容器,用于可能与广告展示相关的买卖双方之间的直接交易。实际交易表示为 的集合。 |
| 对象 | 如需了解更多信息,请参阅有关 的部分。 | 用于描述项目或应用程序的对象。 |
| 对象 | 如需了解更多信息,请参阅有关 的部分。 | 用于描述用户设备的对象。 |
| 对象 | 如需了解更多信息,请参阅有关数据隐私的文档。 | 用于表示设备真实用户或广告受众的对象。 |
| 整型 | | 使用的广告竞价类型。所有 Unity Exchange 广告竞价都是第一高价广告竞价,因此该值始终为 。 |
| 整型 | | 超时值(以毫秒为单位)。注意 Unity 建议合作伙伴在 200 毫秒内做出响应,以免网络连接中断。 |
| 字符串数组 | "bcat": ["IAB9-9", "IAB8"]
| 需屏蔽的广告主类别(使用 IAB 分类 ID 表示)。 |
| 字符串数组 | "bapp": ["com.foo.mygame"]
| 被屏蔽的应用程序列表,由其特定平台表示。在 Android 上,这些是捆绑包名或软件包名。在 iOS 上,这些是数字 ID。 |
| 对象 | 如需了解更多信息,请参阅有关 的部分。 | 此对象提供关于库存来源的数据以及关于哪个实体做出最终决策的信息。 |
| 对象 | 如需了解更多信息,请参阅有关数据隐私的文档。 | 此对象用于指定针对该请求实施的任何行业法规, 法律法规或政府法规。 |
source 对象
一种描述交易平台上游广告请求来源实体的性质和行为的对象类。此对象的主要目的是在交易平台本身不控制最终决策时定义竞价后或上游的决策。如需了解更多信息,请参阅 OpenRTB 指南的对象:source (Object: source) 部分。
schain 对象
此对象既表示供应链中的链接,也表示供应链信息是否完整。
属性 | 类型 | 示例 | 描述 |
|---|
| 整型 | | 此标志指示供应链中是否包含交易涉及的所有节点,这些节点导向回库存网站, 应用或其他媒介的所有者。 |
| 对象数组 | 需要示例 | 按供应链顺序排列的 对象数组。在完整供应链中,第一个节点表示交易中涉及的初始广告系统和卖家 ID(例如网站, 应用或其他媒介的所有者)。在不完整供应链中,表示的是第一个已知节点。最后一个节点表示发送此广告请求的实体。 |
| 字符串 | | 正在使用的供应链规范版本,格式为 。 |
nodes 对象
一个用于表示交易供应链中涉及的实体的对象。
属性 | 类型 | 示例 | 描述 |
|---|
| 字符串 | | 出价者连接到的系统域名。如果它与父级企业域名不同,可能是系统的运营域名。如果存在 文件,此值应与 app-ads.txt 文件中用于识别卖家的值相同。 |
| 字符串 | | 与广告系统中的卖家或经销商帐户关联的 ID。必须包含 OpenRTB 交易中使用的相同值。通常为 。应将此字段的长度限制在 64 个字符内。 |
| 字符串 | "rid":"582f5fb3-0cc6-4944-ab12-1233175675e8-9999-36946"
| 此卖家发出的请求的 OpenRTB 。 |
| 整型 | | 指示此节点是否参与库存的支付流程。
- 表示此节点不参与支付流程。
- 表示 asi 字段中的广告系统向 sid 字段中的卖家付款,卖家负责向供应链中的前一个节点付款。
|
imp 对象
此对象类描述正在参与竞价的广告展示。
属性 | 类型 | 示例 | 描述 |
|---|
| 对象 | 如需了解更多信息,请参阅有关 对象的部分。 | 用于描述横幅广告展示的对象。注意 Unity 仅为横幅广告和展示性广告传递此属性。 |
| 浮点 | | 赢得此广告展示所需的最低单次展示成本 (CPM) 出价。以美元为单位。 |
| 字符串 | "displaymanager": "unity sdk"
| 负责展示广告的广告聚合合作伙伴, SDK 技术或播放器的名称。 |
| 字符串 | | 负责展示广告的广告聚合合作伙伴, SDK 技术或播放器的版本。 |
| 字符串 | | 对于每个广告请求,Unity 支持一个 对象,因此 值始终为 。 |
| 整型 | | 横幅广告请求的值为 ;所有其他广告位均为插页式广告,其值为 。 |
| 整型 | | Unity 要求广告展示必须具有安全的 创意资源和标记;该值始终为 。 |
| 字符串 | "tagid": "com.this.game-video"
| Unity 以标识符的形式传递 。 |
| 对象 | 如需了解更多信息,请参阅有关 video 对象的部分。 | 用于描述视频广告展示的对象。 |
| 对象 | 如需了解更多信息,请参阅有关 iOS 14 支持的文档。 | 如果 DSP 在发布者应用的 文件中至少有一个 ,Unity 将在广告请求中包含此对象。此对象提供创建签名所需的信息。 |
| 整数 | | 指示是否有资格使用 SKOverlay 功能。
- 表示 imp 符合显示 SKOverlay 的条件。
- 表示 imp 不符合显示 SKOverlay 的条件。
|
| 整数 | | 指示是否有资格使用 Custom Product Page 功能。
- 表示 imp 符合显示 Custom Product Page 的条件。
- 表示 imp 不符合显示 Custom Product Page 的条件。
|
| 整数 | | 指示是否有资格使用 Auto Storekit 功能。
- 表示 imp 符合显示 Auto Storekit 的条件。
- 表示 imp 不符合显示 Auto Storekit 的条件。
|
video 对象
用于描述视频广告展示的 对象类的子集。如需了解更多信息,请参阅 OpenRTB 规范中的第 3.2.7 节。
属性 | 类型 | 示例 | 描述 |
|---|
| 整型数组 | | 此广告展示支持的 API 框架。值为 表示支持 Open Measurement。如需了解更多信息,请参阅有关 OM 扩展的文档。 |
| 整型数组 | "battr": [ 1, 3, 5, 6, 8, 9, 13]
| 被屏蔽的广告素材属性数组。如需查看支持值的完整列表,请参阅 OpenRTB 规范中的表 5.3。注意 依 Unity 的政策,会默认屏蔽以下广告内容:
- 音频广告(自动播放)
- 可展开内容(自动)
- 可展开内容(用户启动 - 翻转)
- 横幅广告内视频广告(自动播放)
- 弹出内容(例如:上方弹出, 下方弹出或退出时弹出)
- 挑衅或挑逗性图片
- 用户交互内容(例如,嵌入式项目)
|
| 整型 | | 视频播放器的高度(以设备独立像素 (DIPS) 为单位)。 |
| 整型 | | 视频广告最大持续时间(以秒为单位)。此值始终为 。 |
| 字符串数组 | "mimes": ["video/mp4","video/webm"]
| 支持的内容 MIME 类型,包括 , 和 VPAID 。 |
| 整型 | | 视频广告最小持续时间(以秒为单位)。此值始终为 。 |
| 整型 | | Unity 支持的视频广告位类型如下: |
| 整型 | | 视频广告在屏幕上的位置。Unity Ads 视频广告库存始终设置为全屏展示 ()。如需查看支持值的完整列表,请参阅 OpenRTB 规范中的表 5.4。 |
| 整型数组 | "protocols": [2, 3, 5, 6]
| 受支持视频协议的数组。如需查看支持值的完整列表,请参阅 OpenRTB 规范中的表 5.8。注意 Unity 完全支持 VAST 2.0 () 和 VAST 2.0 封装器 (),并可支持 VAST 3.0 () 和 VAST 3.0 封装器 () 的部分功能。有关详细信息,请与客户经理联系。 |
| 整型 | | 视频播放器的宽度(以设备独立像素 (DIPS) 为单位)。 |
| 整型数组 | | 可支持的结束页类型数组,包含 (), () 和 ()。 |
| 整型 | | 指示广告展示是否必须是线性的。对于 Unity Exchange,此值始终为 。 |
| 整型 | | 指示是否可以跳过视频,其中:对于 Unity Exchange,此值始终为 。 |
| 整型 | | 如果同一个广告请求收到了多个广告展示的机会,则可以通过序号来协调多个广告素材的交付。对于 Unity Exchange,此值始终为 。 |
banner 对象
一个用于描述横幅广告展示的 对象类的子集。如需了解更多信息,请参阅 OpenRTB 规范中的第 3.2.6 节。
属性 | 类型 | 示例 | 描述 |
|---|
| 整型数组 | | 发布者支持的横幅广告 API 框架。Unity 支持 MRAID 3.0 ()。如需查看支持值的完整列表,请参阅 OpenRTB 规范中的表 5.6 API 框架。 |
| 整型数组 | "battr": [ 1, 3, 5, 6, 8, 9]
| 被屏蔽的横幅广告素材属性数组。如需查看支持值的完整列表,请参阅 OpenRTB 规范中的表 5.3。注意 依 Unity 的政策,会默认屏蔽以下广告内容:
- 音频广告(自动播放)
- 可展开内容(自动)
- 可展开内容(用户启动 - 翻转)
- 横幅广告内视频广告(自动播放)
- 弹出内容(例如:上方弹出, 下方弹出或退出时弹出)
- 挑衅或挑逗性图片
|
| 对象数组 | "format": [{"w":728, "h":90}]
| 用于表示支持的横幅广告尺寸的对象数组。横幅广告素材格式支持的尺寸:展示性广告素材格式支持的尺寸:
- 250x300
- 300x250
- 320x480
- 1024x768
注意 仅为移动端横幅广告和插页式展示性广告请求传递 对象。如果未指定格式,则尺寸默认为 和 值。如果未指定横幅广告格式,则尺寸默认为 和 值。如果对支持的不同尺寸有疑问,请联系 Unity 支持人员。 |
| 整型 | | 横幅广告展示的高度(以设备独立像素 (DIPS) 为单位)。 |
| 整型 | | 横幅广告的位置。如需查看支持值的完整列表,请参阅 OpenRTB 规范中的表 5.4。 |
| 整型 | | 横幅广告展示的宽度(以设备独立像素 (DIPS) 为单位)。 |
pmp 对象
一种描述私有市场属性(适用于可能与广告展示相关的买卖双方之间的直接交易)的对象类。如需了解更多信息,请参阅 OpenRTB 规范中的第 3.2.11 节。
属性 | 类型 | 示例 | 描述 |
|---|
| 对象数组 | 如需了解更多信息,请参阅有关 的部分。 | 一组 对象,用于传达适用于此次展示机会的特定交易。 |
| 整型 | | 指示 对象中指定席位的广告竞价资格:
- (默认值)表示接受所有出价。
- 表示出价仅限于指定的交易及其条款。
|
deal 对象
一种描述在买卖双方之间建立的特定交易的对象类。它的存在表明可以根据该交易的条款进行广告展示。如需了解更多信息,请参阅 OpenRTB 规范中的第 3.2.12 节。
属性 | 类型 | 示例 | 描述 |
|---|
| 整型 | | 广告请求的广告竞价类型的可选覆盖:
- 表示第一高价广告竞价。
- 表示二价广告竞价。
- 表示传入 的值是商定的交易价格。
|
| 字符串 | | 直接交易的唯一标识符。 |
app 对象
一种描述发出广告请求的应用程序的对象类。如需了解更多信息,请参阅 OpenRTB 规范中的第 3.2.14 节。
属性 | 类型 | 示例 | 描述 |
|---|
| 字符串 | Google 示例:
"bundle": "com.unityexample.game"
Apple 示例: | 应用程序的包名(Bundle ID或package name),需具有跨广告交易平台的唯一性。
- Android 应用传递 Bundle ID。
- iOS 应用传递 Bundle ID 或 Store ID。
注意 在特定情况下,可能无法传递该属性,如:当发布者在合同协议中要求禁止提供时。 |
| 字符串 | "id": "a1b2c3d4e5f6g7h8i9j0123456789abc"
| 特定于广告交易平台的应用程序 ID。 |
| 字符串 | | 应用程序名称。注意 在特定情况下,可能无法传递该属性,如:当发布者在合同协议中要求禁止提供时。 |
| 对象 | "publisher":"ExamplePublisher"
| 特定于广告交易平台的发布者 ID。 |
| 字符串 | "storeurl": "https://itunes.apple.com/us/app/trash-dash/id1198634425?mt=8"
| 已安装应用的商店链接(为了实现 QAG 1.5 合规性)。在特定情况下,可能无法传递该属性,如:当发布者在合同协议中要求禁止提供时。 |
publisher 对象
一种描述发出广告请求的发布者的对象类。如需了解更多信息,请参阅 OpenRTB 规范中的第 3.2.15 节。
属性 | 类型 | 示例 | 描述 |
|---|
| 字符串 | "id": "a1b2c3d4e5f6g7h8i9j0123456789abc"
| 特定于广告交易平台的发布者 ID。 |
device 对象
一种描述终端用户设备的对象类。如需了解更多信息,请参阅 OpenRTB 规范中的第 3.2.18 节。
属性 | 类型 | 示例 | 描述 |
|---|
| 整型 | | 网络连接类型。如需查看支持值的完整列表,请参阅 OpenRTB 规范中的表 5.22。 |
| 整型 | | 设备的一般类型。如需查看支持值的完整列表,请参阅 OpenRTB 规范中的表 5.21。
请注意,OpenRTB 2.2 版中引入了手机与平板电脑之间的区分: |
| 对象 | "geo": {"lat":34.0544,"lon":-118.2441,"type":2,"country":"USA","region":"CA","city":"Los Angeles","utcoffset":-480}
| 设备的定位数据(假定为用户的当前定位): |
| 字符串 | "hwv": "samsung SM-J200H"
| 设备的硬件版本。 |
| 字符串 | "ifa": "ab12c456-78de-90f1-ghi2-j3kl4567890m"
| 明确批准供广告主使用的 Android 广告 ID (AID) 或 iOS 广告标识符 (IFA/IDFA)(非哈希值)。 |
| 字符串 | | 设备的 IP 地址。 |
| 字符串 | | 浏览器语言,使用 ISO-639-1-alpha-2 代码。 |
| 整型 | | 已获商业认可的"Limit Ad Tracking(限制广告追踪)"信号。
- 表示追踪不受限制。
- 表示根据商业准则必须限制追踪。
Unity 在值为 时始终传递此属性,而在值为 时忽略此属性。 |
| 字符串 | | 设备的制造商。 |
| 字符串 | | 设备的型号。 |
| 字符串 | | 设备的操作系统。 |
| 字符串 | | 设备的操作系统版本。 |
| 字符串 | "ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 10_0 like Mac OS X)
AppleWebKit/602.1.50 (KHTML, like Gecko) Mobile/14A345"
| Web 浏览器端的用户代理字符串。 |
| 字符串 | | 设备运营商。 |
广告请求示例
VAST 广告请求
{ "id": "bcaIDT1Nbv0zU8mn9tXQ6j", "at": 1, "tmax": 200, "source": { "pchain": "12abcd3456789:12345" "omidpn": "Unity3d", "omidpv": "1.3.0" }, "imp": [{ "id": "1", "secure": 1, "instl": 1, "tagid": "com.unity3d.ads.example-vast", "bidfloor": 3.95, "video": { "mimes": [ "video/mp4","video/webm","application/javascript" ], "minduration": 5, "maxduration": 30, "placement": 5 "protocols": [2, 3, 5, 6], "pos": 7, "battr": [1, 3, 5, 8, 9, 13], "w": 1024, "h": 600, "api": [7], "companiontype": [1,2,3] } "displaymanager": "unity sdk", "displaymanagerver": "4001", "ext": { "skadn": { "ext": { "ask": 1 }, "skoverlay": 1, "productpage": 1 } } }], "app": { "id": "d01234idnfld234ier6c70930a", "name": "Build A Town: All the games", "publisher": { "id": "11972001l" }, "bundle": "12312312399", "storeurl": "https://apps.apple.com/us/app/build-a-town/id12312312399" }, "device": { "ifa": "ab12c456-78de-90f1-ghi2-j3kl4567890m", "make": "Apple", "model": "iPhone", "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 10_0 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Mobile/14A345", "os": "ios", "ip": "12.34.5.6", "devicetype": 4, "carrier": "Apple", "osv": "10.1", "hwv": "iphone6", "geo": { "lat": 55.5492, "lon": 59.0456, "country": "USA", "city": "San Francisco", "type": 2, "utcoffset": 180 }, "connectiontype": 3, "language": "en", "h": 1184, "w": 768 }, "regs": { "coppa": 0 }}
VPAID 广告请求
{ "id": "bcda7938-14eb-4a46-8dcb-bcd7587a964f", "imp": [ { "id": "1", "video": { "mimes": [ "video/mp4", "application/javascript" ], "minduration": 5, "maxduration": 30, "protocols": [ 2, 3, 5, 6 ], "w": 320, "h": 480, "linearity": 1, "sequence": 1, "battr": [ 1, 3, 5, 6, 8, 9, 13 ], "pos": 7, "api": [ 2 ] }, "pmp": {}, "displaymanager": "unity sdk", "displaymanagerver": "3000", "instl": 1, "tagid": "com.unity3d.unityads.AdOpsTools.enterprise-vast", "bidfloor": 3.95, "secure": 1 "ext": { "skadn": { "ext": { "ask": 1 }, "skoverlay": 1, "productpage": 1 } } }], "app": { "id": "d01234idnfld234ier6c70930a", "name": "Build A Town: All the games", "publisher": { "id": "11972001l" }, "bundle": "12312312399", "storeurl": "https://apps.apple.com/us/app/build-a-town/id12312312399" }, "device": { "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_1 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12B411", "geo": { "lat": 37.7958, "lon": -122.4203, "type": 2, "country": "USA", "region": "CA", "city": "San Francisco", "utcoffset": -480 }, "ip": "4.14.109.2", "devicetype": 4, "model": "iPhone7,1", "os": "ios", "osv": "8.1", "hwv": "iPhone 6 Plus", "h": 716, "w": 414, "language": "en", "carrier": "dna", "connectiontype": 2, "ifa": "36E493A2-8E81-4CAE-B85A-1B9786E3C9F2" }, "at": 1, "tmax": 500, "regs": { "ext": {} }, "ext": { "sessionDepth": 7 }}
横幅广告请求
{ "id": "bcda7938-14eb-4a46-8dcb-bcd7587a964f", "imp": [ { "id": "1", "banner": { "w": 320, "h": 50, "battr": [ 1, 3, 5, 6, 8, 9, 13 ] }, "pmp": {}, "displaymanager": "unity sdk", "displaymanagerver": "3200", "tagid": "com.unity3d.ads.opstool-banner", "bidfloor": 3.95, "secure": 1 } ], "app": { "id": "2aa377f91oo12398465d6af383", "name": "Example Game: Chapter Two", "publisher": { "id": "189857700" }, "bundle": "com.devexample.thegamebundlename", "storeurl": "https://play.google.com/store/apps/details?id=com.devexample.thegamebundlename\u0026hl=en" }, "device": { "ua": "Mozilla/5.0 (Linux; Android 9; Pixel Build/PQ3A.190705.001; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/75.0.3770.101 Mobile Safari/537.36", "geo": { "lat": 37.7958, "lon": -122.4203, "type": 2, "country": "USA", "region": "CA", "city": "San Francisco", "utcoffset": -480 }, "ip": "4.14.109.3", "devicetype": 4, "make": "Google", "model": "Pixel", "os": "android", "osv": "9.0", "hwv": "Google Pixel", "w": 320, "h": 50, "language": "en", "connectiontype": 2, "ifa": "d0a77d1b-e974-41f3-84c5-8fe75718ef2d" }, "at": 1, "tmax": 500, "regs": { "ext": {} }, "ext": { "sessionDepth": 1 }}
试玩广告请求
{ "id": "abcIDT1Def0zU8mn9gHI6j", "source": { "pchain": "12abcd3456789:12345" }, "imp": [{ "id": "1", "banner": { "w": 1024, "h": 768, "battr": [1, 3, 5, 6, 8, 9], "pos": 7, "api": [5] }, "displaymanager": "unity sdk", "displaymanagerver": "4000", "instl": 1, "tagid": "com.unity-game.trashdash-m3-ios-display", "bidfloor": 3.95, "secure": 1 }], "app": { "id": "d01234idnfld234ier6c70930a", "name": "Build A Town: All the games", "publisher": { "id": "11972001l" }, "bundle": "12312312399", "storeurl": "https://apps.apple.com/us/app/build-a-town/id12312312399" }, "device": { "ifa": "ab12c456-78de-90f1-ghi2-j3kl4567890m", "ua": "Mozilla/5.0 (iPad; CPU OS 11_2_2 like Mac OS X) AppleWebKit/604.4.7 (KHTML, like Gecko) Mobile/15C202", "geo": { "lat": 55.5492, "lon": 59.0456, "country": "USA", "city": "San Francisco", "type": 2, "utcoffset": 180 }, "ip": "12.34.5.6", "devicetype": 5, "model": "iPad5,3", "os": "ios", "osv": "11.2.2", "hwv": "iPad Air 2 (Wi-Fi)", "h": 768, "w": 1024, "language": "en", "connectiontype": 2 }, "at": 1, "tmax": 200, "regs": {}, "ext": {} }
插页式展示性广告请求
{ "id": "ApJv9QAmN3FJjEcTtFDtW3", "imp": [{ "id": "1", "banner": { "w": 480, "h": 320, "format": [ {"w":250,"h":300}, {"w":300,"h":250}, {"w":480,"h":320}, {"w":320,"h":480} ], "battr": [1, 3, 5, 6, 8, 9, 13], "pos": 7, "api": [5] }, "displaymanager": "unity sdk", "displaymanagerver": "3750", "instl": 1, "tagid": "com.unity3d.ads.example-display", "bidfloor": 3.95, "secure": 1 }], "app": { "id": "2aa377f91oo12398465d6af383", "name": "Example Game: Chapter Two", "publisher": { "id": "189857700" }, "bundle": "com.devexample.thegamebundlename", "storeurl": "https://play.google.com/store/apps/details?id=com.devexample.thegamebundlename\u0026hl=en" }, "device": { "ua": "Mozilla/5.0 (Linux; Android 5.1.1; SM-J200H Build/LMY48B; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/64.0.3282.137 Mobile Safari/537.36", "geo": { "lat": 55.5492, "lon": 59.0456, "country": "USA", "city": "San Francisco", "type": 2, "utcoffset": 180 }, "source": { "pchain": "12abcd3456789:12345" }, "ip": "12.34.5.6", "devicetype": 4, "make": "samsung", "model": "SM-J200H", "os": "android", "osv": "5.1", "hwv": "samsung SM-J200H", "h": 540, "w": 960, "language": "ru", "carrier": "Tele2", "connectiontype": 2, "ifa": "dd92e219-68ae-43b9-bcb7-e6fb7557806e" }, "at": 1, "tmax": 200, "regs": {}, "ext": { "placementType":"nonrewarded", "Mute":false, "gameCategory":"Applications", "subGameCategory":"Tools", "sessionDepth":0 }}