# 试玩广告和交互式广告

> 通过 Unity Exchange 投放交互式试玩广告。

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

## MRAID##mraid

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

## 识别和初始化##identification-and-initialization

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

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

```js
 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` 表示不是面向儿童。                  |

> **Note:**
>
> Unity 不支持 `ifa` 属性。

如需了解如何识别和初始化 MRAID 功能的更多信息，请参阅 [IAB 文档](https://www.iab.com/wp-content/uploads/2015/08/IAB_MRAID_v2_FINAL.pdf)。

## 事件##events

广告必须注册事件监听器才可以接收以下事件。如需了解更多信息，请参阅 [`addEventListener`](#addeventlistener) 和 [`removeEventListener`](#removeeventlistener) 方法。

### error##error

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

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

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

### ready##ready

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

`ready()`

### sizeChange##sizechange

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

`sizeChange(width: number, height: number)`

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

### stateChange##statechange

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

`stateChange(state: string)`

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

### exposureChange##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

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

`audioVolumeChange(volumePercentage: number): void`

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

### viewableChange（已弃用）##viewable-change

> **Important:**
>
> 此事件在 MRAID 3.0 中已弃用。但是，Unity 仍然支持它以保持向后兼容性。

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

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

`viewableChange(viewable: boolean): void`

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

## 支持的方法##supported-methods

Unity 支持以下 MRAID 方法：

* [addEventListener](#addeventlistener)
* [close](#close)
* [getCurrentAppOrientation](#getcurrentapporientation)
* [getCurrentPosition](#getcurrentposition)
* [getDefaultPosition](#getdefaultposition)
* [getMaxSize](#getmaxsize)
* [getplacementtype](#getplacementtype)
* [getScreenSize](#getscreensize)
* [getState](#getstate)
* [getVersion](#getversion)
* [isViewable](#isviewable)
* [open](#open)
* [removeEventListener](#removeeventlistener)
* [supports](#supports)
* [unload](#unload)

### addEventListener##addeventlistener

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

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

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

> **Note:**
>
> 当不再使用事件监听器时，应始终将其移除。如需了解更多信息，请参阅有关 [removeEventListener](#removeeventlistener) 方法的文档。

### close##close

使用此方法可降级广告容器的状态。由于 Unity 目前不同时支持 `expand` 和 `resize` 方法，因此该方法只能将广告从默认状态更改为隐藏状态。

`close():void`

> **Note:**
>
> 此方法会触发 `stateChange` 事件。

### getCurrentAppOrientation##getcurrentapporientation

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

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

#### 返回值##return-values

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

### getCurrentPosition##getcurrentposition

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

`getCurrentPosition():JavaScriptObject`

#### 返回值##return-values

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

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

### getDefaultPosition##getdefaultposition

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

`getDefaultPosition():JavaScriptObject`

#### 返回值##return-values

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

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

### getMaxSize##getmaxsize

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

`getMaxSize():JavaScriptObject`

#### 返回值##return-values

`{width: number, height: number}`

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

### getplacementtype##getplacementtype

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

`getplacementtype():string`

#### 返回值##return-values

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

### getScreenSize##getscreensize

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

`getScreenSize():JavaScriptObject`

#### 返回值##return-values

`{width: number, height: number}`

| **值**    | **描述**             |
| -------- | ------------------ |
| `width`  | 屏幕大小的最大宽度（以像素为单位）。 |
| `height` | 屏幕大小的最大高度（以像素为单位）。 |

### getState##getstate

此方法返回广告容器的当前状态。因为 Unity 不支持 `expand` 和 `resize` 方法，所以广告状态始终不会返回 `"expanded"` 或 `"resized"` 值。

`getState(): string`

#### 返回值##return-values

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

### getVersion##getversion

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

`getVersion():string`

#### 返回值##return-values

| **值** | **描述**               |
| ----- | -------------------- |
| `3.0` | 表示 MRAID 接口为 3.0 版本。 |

### isViewable（已弃用）##isviewable

> **Important:**
>
> 此事件已弃用。但是，Unity 仍然支持它以保持向后兼容性。

此方法返回广告容器当前是在屏幕上还是在屏幕外。

`isViewable():boolean`

**返回值**

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

> **Note:**
>
> 此方法会触发 `viewableChange` 事件。

### open##open

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

`open(url:string):void`

#### 参数##parameters

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

### removeEventListener##removeeventlistener

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

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

#### 参数##parameters

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

### supports##supports

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

`supports(feature:string):boolean`

#### 参数##parameters

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

**返回值**

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

### unload##unload

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

`unload(): void`

## 不支持的方法##unsupported-methods

Unity 不支持以下方法：

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

## 故障排除##troubleshooting

如果您收到类似以下示例的 `Uncaught TypeError`，可能表示 MRAID 接口尚不可用，或者广告素材未能包含 `<MRAID>` 脚本标签，因此从未附加该接口。

### 示例##example

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

如果您尝试在不包含 `<MRAID>` 脚本标签的情况下调用 `getVersion` 方法，则会发生此错误。要修正此问题，请在代码中较靠前的位置添加脚本标签，然后再引用任何 MRAID 函数。