试玩广告和交互式广告

Deliver interactive playable ads through Unity Exchange.

阅读时间 8 分钟

最后更新 3 days ago

试玩广告是 Unity Exchange 上第二受欢迎的广告类型。由于所有的 Unity 广告库存均为移动应用内广告，因此大部分都支持试玩广告。

MRAID

移动富媒体广告接口定义 (MRAID) 是在移动应用中投放移动富媒体广告的通用 API。MRAID 让广告开发者可以使用通用代码设计出能够在符合 MRAID 标准的系统中运行的交互式广告。MRAID 可以控制广告在应用中的交互方式。

识别和初始化

为确保您的广告与 Unity MRAID 接口兼容，请执行以下操作：

在引用任何 MRAID 函数之前，尽早在广告代码中包含 MRAID 脚本标签 (
```
<script src="mraid.js"></script>
```
)，将广告标识为符合 MRAID 标准。
使用
```
addEventListener
```
函数监测 MRAID 状态从"loading"变为"ready"的情况。
在展示广告之前使用
```
getState
```
方法验证"ready"状态。这样做可以防止时序问题，例如在注册广告之前就触发就绪事件。


function showMyAd() {
  // Ad content
}

if (mraid.getState() === ‘loading') {
   mraid.addEventListener(‘ready', showMyAd);
} else {
   showMyAd();
}

访问

MRAID_ENV

对象可以在初始化之前验证您需要的任何其他信息。此变量附加到窗口对象，并包含以下属性：

属性	类型	示例	描述
`version`	字符串	`"3.0"`	实现 MRAID 接口的版本。
`sdk`	字符串	`"The Unity Ads SDK"`	运行 Web 视图的 SDK 名称。
`sdkVersion`	字符串	`"4.0"`	运行 Web 视图的 SDK 版本。
`appId`	字符串	`"com.unity3d.ads.example"`	运行广告的应用程序的包名或应用程序 ID。
`limitAdTracking`	布尔值	`true`	`true` 表示启用 Limit Ad Tracking（限制广告追踪）， `false` 表示禁用。
`coppa`	布尔值	`true`	`true` 表示该应用面向儿童， `false` 表示不是面向儿童。

注意

Unity 不支持

ifa

属性。

如需了解如何识别和初始化 MRAID 功能的更多信息，请参阅 IAB 文档。

事件

广告必须注册事件监听器才可以接收以下事件。如需了解更多信息，请参阅

addEventListener

和

removeEventListener

方法。

error

客户端无法执行广告调用的方法（函数）时，便会触发此事件。

error(message: string, action: string): void

参数	类型	描述
`message`	字符串	错误描述。
`action`	字符串	触发错误时调用的 MRAID 操作的名称。

ready

在初始化完成时触发此事件。

ready()

sizeChange

只要广告容器尺寸发生变化（例如，随设备方向变化而变化），便会触发此事件。

sizeChange(width: number, height: number)

参数	类型	描述
`width`	数字	新视图的宽度。
`height`	数字	新视图的高度。

stateChange

只要广告容器的状态发生变化，便会触发此事件。

stateChange(state: string)

参数	类型	描述
`state`	字符串	广告容器的状态指示。此状态可以是 `"loading"` , `"default"` 或 `"hidden"` 。

exposureChange

只要广告的曝光发生变化，便会触发此事件。示例包括：

广告展示时。
广告关闭时。
应用程序有前景或背景时。
广告容器的曝光界面被更改时（例如，用户打开隐私设置）。

exposureChange(exposedPercentage: number, visibleRectangle: Rectangle | null, occlusionRectangles: Rectangle[] | null)

参数	类型	描述
`exposedPercentage`	数字	广告在屏幕上可见的百分比（介于 `0.0` 和 `100.0` 之间）。
`visibleRectangle`	`Rectangle`	广告容器的可见部分，格式为 `{x, y, width, height}` 。如果完全不可见，则返回 `null` 。
`occlusionRectangles`	`Rectangle` 数组	一个描述 `visibleRectangle` 任何不可见部分的矩形数组，如果整个矩形可见，则为 `null` 。数组中的每个遮挡矩形的格式为 `{x, y, width, height}` 。

audioVolumeChange

只要设备的音量发生变化，便会触发此事件。

audioVolumeChange(volumePercentage: number): void

参数	类型	描述
`volumePercentage`	数字	设备上设置的最大音量的百分比（介于 `0.0` 和 `100.0` 之间）。

viewableChange（已弃用）

此事件在 MRAID 3.0 中已弃用。但是，Unity 仍然支持它以保持向后兼容性。只要广告的可视性发生变化，便会触发此事件。示例包括：

广告展示时。
广告关闭时。
应用程序有前景或背景时。

viewableChange(viewable: boolean): void

参数	类型	描述
`viewable`	布尔值	`true` 表示广告容器在屏幕上， `false` 表示不在屏幕上。

支持的方法

Unity 支持以下 MRAID 方法：

addEventListener
close
getCurrentAppOrientation
getCurrentPosition
getDefaultPosition
getMaxSize
getplacementtype
getScreenSize
getState
getVersion
isViewable
open
removeEventListener
supports
unload

addEventListener

使用此方法可将特定处理程序函数订阅到特定事件。多个监听器可以订阅到特定事件，单个监听器可以处理多个事件。

addEventListener(event: string, listener: function): void

参数	类型	描述
`event`	字符串	要监听的事件名称。如需查看完整列表，请参阅有关事件的部分。
`listener`	对象	触发事件时要执行的函数。

注意

当不再使用事件监听器时，应将其移除。如需了解更多信息，请参阅有关 removeEventListener 方法的文档。

close

使用此方法可降级广告容器的状态。由于 Unity 目前不同时支持

expand

和

resize

方法，因此该方法只能将广告从默认状态更改为隐藏状态。

close():void

注意

此方法会触发

stateChange

事件。

getCurrentAppOrientation

使用此方法可向设备查询应用的当前方向。

getCurrentAppOrientation(): { orientation: string, locked: boolean }

返回值

值	描述
`orientation`	一个描述应用方向的字符串。此值可以是 `"landscape"` 或 `"portrait"` 。
`locked`	一个布尔值，指示方向是否锁定在其当前位置，其中 true 指示方向已锁定。锁定方向后不支持 `setOrientationProperties` 中的 `forceOrientation` 属性。

getCurrentPosition

使用此方法可返回广告视图的当前位置和大小（采用与密度无关的像素为单位）。

getCurrentPosition():JavaScriptObject

返回值

{x: number, y: number, width: number, height: number}

值	描述
`x`	从 `getMaxSize()` 定义的矩形左边缘偏移的像素数。
`y`	从 `getMaxSize()` 定义的矩形上边缘偏移的像素数。
`width`	容器的当前宽度（以像素为单位）。
`height`	容器的当前高度（以像素为单位）。

getDefaultPosition

使用此方法可返回默认广告视图的位置和大小（采用与密度无关的像素为单位，不管调用视图处于什么状态）。

getDefaultPosition():JavaScriptObject

返回值

{x: number, y: number, width: number, height: number}

值	描述
`x`	从 `getMaxSize()` 定义的矩形左边缘偏移的像素数。
`y`	从 `getMaxSize()` 定义的矩形上边缘偏移的像素数。
`width`	容器的当前宽度（以像素为单位）。
`height`	容器的当前高度（以像素为单位）。

getMaxSize

由于 Unity 不支持

expand

和

resize

方法，因此该方法始终返回广告容器的最大大小（采用与密度无关的像素宽度和高度）。全屏插页式广告的返回值始终是全屏尺寸。

getMaxSize():JavaScriptObject

返回值

{width: number, height: number}

值	描述
`width`	容器的当前宽度（以像素为单位）。
`height`	容器的当前高度（以像素为单位）。

getplacementtype

此方法返回广告位的类型，这可能会影响广告素材的行为。

getplacementtype():string

返回值

值	描述
`"inline"`	表示内嵌广告位。
`"interstitial"`	表示插页式广告位。

getScreenSize

此方法根据当前方向返回运行广告的设备的实际像素宽度和高度（采用与密度无关的像素为单位）。

getScreenSize():JavaScriptObject

返回值

{width: number, height: number}

值	描述
`width`	屏幕尺寸的最大宽度（单位：像素）。
`height`	屏幕尺寸的最大高度（单位：像素）。

getState

此方法返回广告容器的当前状态。因为 Unity 不支持

expand

和

resize

方法，所以广告状态始终不会返回

"expanded"

或

"resized"

值。

getState(): string

返回值

值	描述
`"default"`	指示广告容器处于其默认可见状态。
`"hidden"`	表示广告容器已隐藏。
`"loading"`	表示广告容器正在加载。

getVersion

此方法返回 Unity 支持的 MRAID 接口版本，可让出价者在展示前确认其基本功能。

getVersion():string

返回值

值	描述
`3.0`	表示 MRAID 接口为 3.0 版。

isViewable（已弃用）

此事件已弃用。但是，Unity 仍然支持它以保持向后兼容性。此方法返回广告容器当前是在屏幕上还是在屏幕外。

isViewable():boolean

返回值

值	描述
`true`	容器在屏幕上并且可见。
`false`	容器在屏幕外并且不可见。

注意

此方法会触发

viewableChange

事件。

open

此方法在应用程序中显示一个加载外部 URL 的嵌入式浏览器窗口。在不允许嵌入浏览器的设备平台上，此方法使用外部 URL 调用原生浏览器。

open(url:string):void

参数

参数	类型	描述
`url`	字符串	外部网页的 URL。

removeEventListener

使用此方法可取消订阅特定事件的特定处理程序方法。当不再使用事件监听器时，应始终将其移除以避免错误。

removeEventListner(event: string, listener: fuction: void)

参数

参数	类型	描述
`event`	字符串	监听器订阅的事件名称，可包括： `"error"` `"ready"` `"sizeChange"` `"stateChange"` `"viewableChange"`
`listener`	函数	要移除的函数。

supports

此方法返回请求设备是否支持特定功能。

supports(feature:string):boolean

参数

参数	类型	描述
`event`	字符串	要查询的功能的名称： `"calendar"` `"inlineVideo"` `"sms"` `"storePicture"` `"tel"`

返回值

值	描述
`true`	设备支持查询的功能。
`false`	设备不支持查询的功能。

unload

此方法通知主机不应再向用户展示广告。如果广告遇到导致其无法正确展示的错误或运行异常时，请使用此方法。

unload(): void

不支持的方法

Unity 不支持以下方法：

```
createCalendarEvent
```
```
expand
```
```
getExpandProperties
```
```
getLocation
```
```
getResizeProperties
```
```
initVpaid
```
```
playVideo
```
```
resize
```
```
setExpandProperties
```
```
setResizeProperties
```
```
storePicture
```
```
useCustomClose
```

故障排除

如果您收到类似以下示例的

Uncaught TypeError

，可能表示 MRAID 接口尚不可用，或者广告素材未能包含

<MRAID>

脚本标签，因此从未附加该接口。

示例

Uncaught TypeError: Cannot read property 'getVersion' of undefined.

如果您尝试在不包含

<MRAID>

脚本标签的情况下调用

getVersion

方法，则会发生此错误。要修正此问题，请先在代码中较靠前的位置添加脚本标签，然后再引用 MRAID 函数。