可玩和互动式广告#

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

MRAID#

移动富媒体广告接口定义 (MRAID) 是在移动应用中运行的移动富媒体广告的通用 API。MRAID 为广告开发者提供了一种方法，让他们可以使用通用代码来设计在兼容 MRAID 的系统中工作的交互式广告。MRAID 控制广告在其出现的应用中的交互方式。

识别和初始化#

为了确保您的广告与 Unity MRAID 接口兼容

• 通过在广告代码中尽可能早地（在引用任何 MRAID 函数之前）包含 MRAID 脚本标签 (<script src=”mraid.js”></script>) 来识别它们是否兼容 MRAID。

• 使用 addEventListener 函数来检测 MRAID 状态何时从“加载”更改为“就绪”。

• 在显示广告之前使用 getState 方法来验证“就绪”状态。这可以防止计时问题，例如就绪事件在广告注册之前触发。

function showMyAd() {
   // Ad content
}

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

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

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

事件#

广告必须注册事件侦听器才能接收以下任何事件。有关更多信息，请参阅 addEventListener 和 removeEventListener 方法。

错误#

当主机无法执行广告调用的函数时，此事件会触发。

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

就绪#

初始化完成后，此事件会触发。

ready()

大小更改#

当广告容器尺寸发生变化时（例如，作为对设备方向更改的响应），此事件会触发。

sizeChange(width: number, height: number)

状态更改#

当广告容器的状态发生变化时，此事件会触发。

stateChange(state: string)

曝光更改#

当广告曝光发生变化时，此事件会触发。例如：

• 广告显示。
• 广告关闭。
• 应用程序处于前台或后台。
• 广告容器的曝光发生改变（例如，用户打开隐私设置）。

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

音频音量更改#

当设备的音量发生变化时，此事件会触发。

audioVolumeChange(volumePercentage: number): void

viewableChange（已弃用）#

重要：此事件已在 MRAID 3.0 中弃用。但是，Unity 仍然支持它以保持向后兼容性。

当广告的可视性发生变化时，此事件会触发。例如：

• 广告显示。
• 广告关闭。
• 应用程序处于前台或后台。

viewableChange(viewable: boolean): void

支持的方法#

Unity 支持以下 MRAID 方法

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

addEventListener#

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

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

close#

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

close():void

getCurrentAppOrientation#

使用此方法查询设备以获取应用的当前方向。

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

返回值#

getCurrentPosition#

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

getCurrentPosition():JavaScriptObject

返回值

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

getDefaultPosition#

使用此方法以密度无关像素为单位返回默认广告视图的位置和大小，而不管调用视图处于何种状态。

getDefaultPosition():JavaScriptObject

返回值

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

getMaxSize#

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

getMaxSize():JavaScriptObject

返回值

{width: number, height: number}

getPlacementType#

此方法返回放置类型，这可能会影响创意的行为。

getPlacementType():string

返回值#

getScreenSize#

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

getScreenSize():JavaScriptObject

返回值

{width: number, height: number}

getState#

此方法返回广告容器的当前状态。由于 Unity 不支持 expand 和 resize 方法，因此广告状态永远不会返回 “expanded” 或 “resized” 值。

getState(): string

返回值#

getVersion#

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

getVersion():string

返回值#

isViewable（已弃用）#

重要：此事件已弃用。但是，Unity 仍然支持它以保持向后兼容性。

此方法返回广告容器当前是否位于屏幕上或屏幕外。

isViewable():boolean

返回值

open#

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

open(url:string):void

参数#

removeEventListener#

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

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

参数#

supports#

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

supports(feature:string):boolean

参数#

返回值

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 函数之前。