MRAID扩展协议

移动富媒体互动广告标准

标签（空格分隔）： MRAID 富媒体广告 互动广告

---

背景说明

在过去的几年中，移动应用上的富媒体广告越来越流行，IAB组织定义的MRAID广告协议已经应用广泛，但是MRAID协议的应用场景是Inline广告及Interstitial广告，并未在视频领域广泛使用，本协议在兼容MRAID 2.0协议的基础上，对播放器的可交互式广告进行了拓展，另外MRAID协议在支持移动终端传感器方面直接依赖了HTML5标准，最新的HTML5标准虽然对各传感器行为进行了定义，但并不是所有的浏览器内核都可以支持，所以本标准对移动终端传感器事件进行了拓展，让更多的移动设备可以使用丰富的传感器交互方式。

广告形式

• 视频前贴片、中插、后贴片
• 视频暂停广告
• 视频框外广告

接口标准

接口概述

1. MRAID 2.0 定义了webview组件展示的创意素材和App之间的交互接口。
2. 视频播放器控制 定义了webview组件展示的创意素材和视频播放器的交互接口。
3. 设备传感器 定义了App和传感器相关功能和webview组件展示的创意素材之间的交互接口，其中方法是指创意js层调用App方法，事件是App、播放器或系统触发的事件，供js层处理。

IAB MRAID v2.0兼容

概述

• 方法列表

  addEventListener
  getVersion
  createCalendarEvent
  isViewable
  close
  open
  expand
  playVideo
  getCurrentPosition
  removeEventListener
  getDefaultPosition
  resize
  getExpandProperties
  setExpandProperties
  getMaxSize
  setResizeProperties
  getPlacementType
  storePicture
  getResizeProperties
  supports
  getScreenSize
  useCustomClose
  getState
  getOrientationProperties
  setOrientationProperties

• 事件列表

  error
  stateChange
  ready
  viewableChange
  sizeChange

初始化

• ready事件
  当容器完全加载、初始化完成并且准备好来自广告创意的任何调用时，ready事件触发。
  在执行任何富媒体操作之前，广告应该等待ready事件。因为一些时间问题，比如要在广告注册监听之前触发ready事件，广告设计者可以配合getState()方法来使用ready事件。
• getVersion方法
  getVersion方法允许广告在显示前确认基础功能集。版本号必须符合MRAID规范（例如1.0或者2.0），不是供应商的SDK版本号。
  

  getVersion() -> String
  参数：
  • none
  返回值
  • String – MRAID兼容的SDK版本号或者IAB针对性认证的SDK版本号。举个例子，对于本文的版本号，getVersion()将返回“2.0”

事件处理

Web层和原生层的通信本质上异步的。通过事件处理，广告设计者能够监听指定的事件，并且可以根据需要响应这些事件。

• addEventListener方法
  使用本方法为指定事件订阅一个指定的处理方法。这样，多个监听器就可以订阅一个指定事件，一个监听器可以处理多个事件。

  addEventListener(event, listener)
  参数：
  • event – String 要监听的事件名称
  • listener – 执行监听的函数
  返回值：
  • none

• removeEventListener方法
  使用本方法从指定事件退订处理方法。当事件监听器不再有用时，它们应当被移除以避免出错。如果没有指定监听器方法，那么正在监听事件的所有方法将被移除。

  removeEventListener(event, listener)
  参数：
  • event – Strign 事件名称
  • listener – 要被移除的函数
  返回值：
  • none
  触发事件：
  • none

错误处理

error事件，每当容器错误发生时，error事件就被触发。该事件包含错误发生时的描述，以及，在适当的时候，包含导致错误的操作名称。

“error” -> function(message, action)
参数：
• message: String 错误描述
• action: String 引发错误的动作

控制广告显示

• getState方法
  返回广告容器的当前状态，返回广告容器是否处于其默认状态，是否是固定位置，是否处于展开或缩放状态，是否是更大的位置，或者是否是隐藏的。

状态	解释
hidden	插播式广告转变为关闭后的状态。在被支持的情况下，banner广告转变为关闭后的状态
resized	广告容器已通过MRAID2.0 resize()方法改变大小
expanded	广告容器已展开覆盖到应用程序内容的最顶层
default	应用程序和SDK设定好广告容器的初始位置和大小

getState() -> String
参数：
• none
返回值：
• String: “loading”或”default”或”expanded”或“resized”或“hidden”
相关事件：
• stateChange

• stateChange事件
  当状态被广告或者环境以程序方式改变时，会触发stateChange事件。当广告视图在default、expanded、resized、hidden状态之间改变时（这些状态都是在调用expand(), resize(), close()产生的）触发stateChange事件。

  “stateChange” -> function(state)
  参数：
  • state - String, “loading”或”default”或”expanded”或“resized”或“hidden”
  经由触发：
  • expand()方法、resize()方法、close()方法或者App

• getPlacementType()方法
  容器返回放置类型的值以便于创意在需要时引发不同的行为。
  值描述：

形式	说明
inline	默认的放置类型是嵌入到内容中显示（即banner）
interstitial	这种广告放置类型是覆盖在内容上面

getPlacementType() -> String
参数：
• none
返回值：
• String: “inline”, “interstitial”
相关事件：
• none

• isViewable方法
  isViewable方法返回广告容器当前是否在屏幕上。

  isViewable() -> boolean
  参数：
  • none
  返回值：
  • boolean -
  true：容器在屏幕上并且对用户可见；
  false：容器不在屏幕上并且不可见
  相关事件：
  • viewableChange

• viewableChange事件

    // Wait for the SDK to become ready
    if (mraid.getState() === 'loading') {
        mraid.addEventListener('ready', onSdkReady);
    } else {
        onSdkReady();
    }

    function onSdkReady() {
        // Wait for the ad to become viewable for the first time
        if (mraid.isViewable()) {
            showMyAd();
        } else {
            mraid.addEventListener('viewableChange',function(viewable) {
                if (viewable) {
                    mraid.removeEventListener('viewableChange', arguments.callee);
                    showMyAd();
                }
            }); 
        }
    }

    function showMyAd() {
    ... 
    }

当广告从屏幕上出现或离开时会触发viewableChange事件

“viewableChange” -> function(isViewable)
参数：
• isViewable - boolean
true：容器在屏幕上并且对用户可见；
false：容器不在屏幕上并且不可见
经由触发：
• 应用程序视图控制器的改变

广告在任何情况下都有可能在屏幕之外加载，最佳实践是：广告检查自身可见状态或者在采取任何行动之前注册viewableChange监听事件。

改变广告尺寸

MRAID2.0包含三种截然不同的方式，用于广告改变尺寸。
- resize()
可完成复杂的广告尺寸变化

resize()
参数：
• none
返回值：
• none
触发事件：
• sizeChange, stateChange
侧面影响：
• 改变状态

• 控制resize属性
  resizeProperties 对象
  resizeProperties object = {
  “width” : integer,
  “height” : integer,
  “offsetX” : integer,
  “offsetY” : integer,
  “customClosePosition” : string,
  “allowOffscreen” : boolean
  }

width: integer —— （必须）创意的像素宽
height: integer —— （必须）创意的像素高
offsetX: —— （必须）TODO
offsetY: —— （必须）TODO
customClosePosition: string —— （可选）”top-right”、”center”、”bottom-left”、”bottom-right”、“top-center”或者“bottom-center”。表示相对于缩放的创意，容器提供的关闭事件区的原点位置。如果没有指定或者不是这些选项之一，默认取”top-right”。
allowOffscreen: —— （可选）告诉容器是否应该允许缩放创意绘制完整/部分的超出屏幕。
True (default): 容器不应试图定位缩放创意。
False: 容器应尽量重新调整缩放创意来适应getMaxSize()的取值。

• getResizeProperties方法
  使用此方法获取广告缩放后的属性。

  getResizeProperties() -> JavaScript Object
  参数：
  • none
  返回值：
  • { … } - 包含resize属性的JS对象
  触发事件：
  • none

• setResizeProperties方法
  使用此方法来设置广告的缩放属性，特别是width和height属性。

setResizeProperties() -> JavaScript Object
参数：
• properties: JavaScript Object { … } —— 这个对象包含要缩放广告的宽和高、关闭位置、偏移方向（都以DIP为单位）、广告是否可以缩放到离开屏幕。更多信息见resizeProperties对象。
返回值：
• none
触发事件：
• none
- expand()
简单的，模态的，增加广告的尺寸
expand([URL])
参数：
• URL (可选): 本文中的URL会在一个新的遮罩视图中显示。如果传入null或者不使用此参数，当前广告的主体会在同一个Web View中使用
返回值：
• none
触发事件：
stateChange

• 控制expand属性
  expand属性是为了给广告设计者提供额外的功能。
  expandProperties object = {
  “width” : integer,
  “height” : integer,
  “useCustomClose” : boolean,
  “isModal” : boolean (read only)
  }

• getExpandProperties 方法
  返回完整的含有expand属性的JavaScript对象。

  getExpandProperties() -> JavaScript Object
  参数：
  • none
  返回值：
  • { … } - this object contains the expand properties
  触发事件:
  • none

• setExpandProperties方法
  设置整个含有expand属性的JavaScript对象。

  setExpandProperties(properties)
  参数：
  • properties: JavaScript Object { … } —— 这个对象包含广告的宽高值，更多属性参考properties对象.
  返回值：
  • none
  触发事件：
  • none

• open()
  在浏览器窗口中打开外部移动站点

  open(URL)
  参数：
  • URL - String, 网页URL
  返回值：
  • None
  关闭展开式广告和插播式广告

• close()
  close方法会使广告容器回到初始状态。对于处在expanded或resized状态的广告，调用close方法会将广告状态变为default。对于处在default状态的插播式广告，调用close方法会将广告状态变为hidden。在本规范中，对于处在default状态的横幅广告，调用close产生的影响未定义，因此一般不建议广告设计者在横幅广告中调用mraid.close()方法

  close()
  参数：
  • none
  返回值：
  • none
  触发事件：
  • stateChange

• useCustomClose 方法
  尽管MRAID要求所有的实现容器必须提供一个含默认关闭图标的可点击区域，但对于广告创建者来说，完全可以使用他们自己设计的关闭指引。
  对于展开式广告，设计者不需要调用此方法，通常在setExpandProperties()方法中设定useCustomClose属性即可。
  对于那些无法调用expand方法的独立插播式广告，但是仍然要求具有MRAID强制关闭选项，广告设计者应在ready事件完成后立即调用该方法。
  这个方法作为expand属性中一个同名属性的快捷方法。设置useCustomClose属性或者调用此方法，两者具有相同的效果，可以互换使用。如果一个广告通过expand属性和此方法都设置了useCustomClose，任何较晚的调用将覆盖较早的设置。他们通知容器停止使用默认的关闭指引。

  useCustomClose(isCustomize)
  参数：
  isCustomize - boolean
  • true —— 广告创意提供它们自己设计的关闭指引
  • false —— 将会显示容器为关闭指引提供的默认图片
  返回值：
  • none
  触发事件：
  • none

注意事项：
超链接
当用户在MRAID广告中点击一个HTML超链接（通过<\a href=”“>标签定义），会有两种可能：目标页面可以在现有的Web View中载入，或者目标页内容可以打开一个独立的浏览器窗口并在那里载入这个链接。兼容MRAID的SDK可以选择两种方式的任何一种，因此广告设计者们应避免使用内嵌超链接和window.location。对于一个标准MRAID广告，指定链接要在单独的浏览器中打开页面时，mraid.open()才是恰当的方法。在广告视图中加载新网页后可以离开广告并没有被写入MRAID规范中，App此时也许处在不可用状态。

控制方向属性

mraid.setOrientationProperties ( {"allowOrientationChange":true} );
mraid.expand()
/* user changes to landscape, starts game */
mraid.setOrientationProperties ( {"allowOrientationChange": false } );
/* user is done with game */
mraid.setOrientationProperties ( {"allowOrientationChange":true} );

orientationProperties object = { 
"allowOrientationChange" : boolean,
"forceOrientation" : "portrait|landscape|none"
}

allowOrientationChange: boolean —— 如果设置为true，广告容器将允许基于设备取向的变化；如果设置为false，则忽略这种变化（例如：即使设备改变方向，Web View也不会改变）。默认值是true。不管allowOrientationChange如何设定，广告创意通过设置forceOrientation的值总是可以改变它们的方向。
forceOrientation: string —— 可以设置portrait、landscape、none其中一个值。如果设置了forceOrientation的值，不管设备的方向如何，视图都必须以特定方向打开。也就是说，如果用户在横屏模式下观看广告，并且点击展开它，如果广告设计者把forceOrientation的属性设置为portrait，那么广告将以竖屏模式打开。默认值为none。

• getOrientationProperties 方法
  getOrientationProperties方法返回完整的含有orientation属性的JavaScript对象。

getOrientationProperties() -> JavaScript Object
参数：
• none
返回值：
• { … } —— 这个对象包含orientation属性。
触发事件：
• none

• setOrientationProperties方法
  设置JavaScript方向属性对象。
  

  setOrientationProperties(properties)
  参数：
  • properties: JavaScript Object { … } —— 这个对象包含allowOrientationChange和forceOrientation的值。
  返回值：
  • none
  触发事件：
  • none

检测屏幕和广告的位置及大小

• getCurrentPosition方法
  getCurrentPosition方法返回广告视图当前的位置和尺寸，以DIP为单位。

  getCurrentPosition() -> JavaScript Object
  参数：
  • none
  返回值：
  • JavaScript Object - {x, y, width, height}：
  x=从getMaxSize方法定义的矩形左边开始的偏移量（DIP为单位）
  y=从getMaxSize方法定义的矩形顶部开始的偏移量（DIP为单位）
  width=当前容器的宽。
  height=当前容器的高。（都是以DIP为单位）
  关联事件：
  • none

• getMaxSize方法
  getMaxSize方法返回广告可以展开到或缩放到的最大尺寸（宽和高都以DIP为单位）。

  getMaxSize() -> JavaScript Object
  参数：
  • none
  返回值：
  • JavaScript Object, {width, height} —— 视图可以增长到的最大宽和高
  关联事件：
  • none

• sizeChange方法
  当广告的尺寸在App界面内发生改变时会触发sizeChange事件。它可能是设备方向改变或调用resize或调用expand方法产生的结果。都是以DIP为单位。
  当广告的Web View的显示状态发生改变时，触发此事件。

“sizeChange” -> function(width, height)
参数：
• width - Number: 视图的宽。
• height - Number: 视图的高。
经由触发：
• 缩放、展开、关闭、方向改变或者在App注册尺寸相关事件监听器后导致广告视图尺寸发生改变时触发。

• getDefaultPosition方法
  不管视图处于何种状态时调用，getDefaultPosition方法都将返回默认广告视图的位置和尺寸（DIP为单位）。

  getDefaultPosition() -> JavaScript Object
  参数：
  • none
  返回值：
  • JavaScript Object - {x, y, width, height}：
  x=从getMaxSize左边开始的偏移量（DIP为单位）；
  y=从getMaxSize顶部开始的偏移量（DIP为单位）；
  width=当前容器的宽；
  height=当前容器的高；

• getScreenSize方法
  getScreenSize方法基于当前方向，以DIP为单位，返回正在运行广告设备的实际像素宽和高。有一点需要注意的是：如果设备从横屏转为竖屏，ScreenSize将发生改变（反之亦然）。另外一点需要注意的是：getScreenSize返回设备屏幕的总计尺寸，包含操作系统给状态栏/系统栏的预留区域，或那些可以被App或广告覆盖的其它区域。

  getScreenSize() -> JavaScript Object
  参数：
  • none
  返回值：
  • {width, height}
  关联事件：

访问本地功能

• supports方法
  supports方法允许广告询问设备支持的指定功能。

属性	值描述
sms	设备支持使用短消息功能：按照协议发送一个短消息
tel	设备支持使用电话功能拨打电话：按协议
calendar	设备可以创建一个日历项
storePicture	设备支持MRAID storePicture方法
inlineVideo	设备可以使用标签播放HTML5视屏文件，并且按着video标签中指定的尺寸（宽和高）播放。这里并不需要以全屏方式播放视频。

> supports(feature) -> Boolean 参数： • String 要检测特性的名称（sms, tel, calendar, storePicture, inlineVideo） return values: • Boolean true —— 支持该功能，并且getter和事件都是可用的。 false —— 当前设备不支持本功能。

#### 用设备的物理特性工作 理论上HTML5的最新标准已经支持，但由于并非所有设备都能支持最新HTML5标准，所以这部分工作，本协议由第三部分予以补充，广告设计人员，监听本文第三部分的事件，将可以获得更多设备的支持 #### 存储图片 调用storePicture方法会在设备相册中放任一张图片。图片可能是本地或者从网络下载的。为了确保用户注意到图片将添加到他们的设备相册，在每张图片的添加过程中，MRAID要求SDK/容器使用操作系统层级的处理器显示模型对话框询问用户确认或取消添加图片。 > storePicture(URI) 参数： • URI - String：图片或其他媒体资源的URI 关联事件： • none #### 创建日历事件 - createCalendarEvent createCalendarEvent({ description: “Mayan Apocalypse/End of World”, location: ‘everywhere’, start: ‘2012-12-21T00:00-05:00, end: ‘2012-12-22T00:00-05:00’ }) > createCalendarEvent(parameters) 参数： • parameters: JavaScript Object {…} —— 对象包含日历事件所需的条目，根据W3C规范指定的日历条目编写。 返回值： • none 关联事件： • none #### 处理视频 移动设备上的视频播放要么通过行内播放（在当前Web View里，App中或移动网页），要么通过打开本地播放器播放。在有可能的情况下，MRAID兼容的容器最好支持行内播放，同时允许广告设计者指定视频创意是以行内播放还是单独播放。广告设计者可以使用“supports(inlineVideo)”方法确定运行创意的设备是否显示行内视频。 - inline播放 为了使内嵌式视频能够播放并且自动播放，MRAID兼容的SDK应向Web View中插入必要的开启标签，这依赖于设备的操作系统类型。 对于iOS设备，必须使用下列标签：

webView.mediaPlaybackRequiresUserAction = NO;
webView.allowsInlineMediaPlayback = YES;

对于Android设备（Honeycomb，Ice Cream Sandwich，还有它们之后的版本），SDK必须请求硬件加速，这些依赖于问题中的视图和它是如何被添加到WindowManager中的：

getWindow().setFlags(WindowManager.LayoutParams.FLAG_HARDWARE_ACCELERATED, WindowManager.LayoutParams.FLAG_HARDWARE_ACCELERATED);

设备/操作系统限制可能会阻止inline视频播放，广告设计者可以使用“supports(inlineVideo)”方法确定运行创意的设备是否显示行内视频。
- playVideo方法
使用此方法通过设备的本机外部播放器在设备上播放视频。

playVideo(URI)
参数：
• URI - String, 视频地址或视频流
返回值：
• none

视频播放器控制 (可选)

概述

 为增加视频前贴、中插、后贴广告的互动能力，需要在视频广告播放器上增加一层Webview来展示HTML5广告，Webview层可以不与视频播放器进行交互，但为了给Webview层以更多的权限，下面定义的方法及事件可以将原来由原生代码实现的功能可以由Webview层来实现，带来更大的灵活性。但这些接口均为可选，实现者可仅通过增加Webview来实现互动能力。

方法列表

mainVideo.addEventListener
mainVideo.removeEventListener
mainVideo.pause
mainVideo.resume
mainVideo.getProgress
mainVideo.expand
mainVideo.shrink
mainAd.addEventListener
mainAd.removeEventListener
mainAd.setObjectViewable

事件列表

durationChange

播放器控制 mainVideo

• mainVideo.pause方法
  暂停主广告播放

  mainVideo.pause()
  参数：
  • none
  返回值：
  • none

• mainVideo.resume方法
  恢复主广告播放

  mainVideo.resume()
  参数：
  • none
  返回值：
  • none

• mainVideo.getProgress方法
  获取当前广告播放进度，以0~1之前的小数表示

  mainVideo.getProgress() -> Number
  参数：
  • none
  返回值：
  Number 0~1小数

• durationChange事件
  获取当前广告时长
  侦听方法：
  mraid.mainVideo.addEventListener(mraid.mainVideo.EVENTS.DURATION_CHANGE, func);
  此事件需配合mraid.stageReady()方法使用，当页面被加载成功后，需调用mraid.stageReady()方法，以上事件才会被触发，传入广告时长

“durationChange” -> function(duration)
参数：
• duration - Number
广告剩余时长
经由触发：
• 广告播放器广告时间改变时触发

• mainVideo.expand方法
  调用接口，将视频放大到全屏

  mainVideo.expand()
  参数：
  • none
  返回值：
  • none

• mainVideo.shrink方法
  调用接口，将视频退出全屏

  mainVideo.shrink()
  参数：
  • none
  返回值：
  • none

HTML5富媒体浮层 mainAd

• mainAd.setObjectViewable方法
  根据不同参数，隐藏/显示相关UI
  

  mainAd.setObjectViewable(number,boolean)
  参数
  • number - Number: 根据不同数值设置需要隐藏/显示的UI
  1:倒计时数字
  2:详情点击按钮
  • boolean - 传入参数设置UI的显示/隐藏效果；true:显示,false:隐藏；
  例：
  隐藏倒计时 mraid.mainAd.setObjectViewable(1, false)
  展示倒计时 mraid.mainAd.setObjectViewable(1, true)
  隐藏点击详情 mraid.mainAd.setObjectViewable(2, false)
  展示点击详情 mraid.mainAd.setObjectViewable(2, true)

设备传感器 (可选)

概述

在HTML5的最新标准中已经定义了手机传感器的事件，但由于手机内置浏览器内核并不都可以支持最新的HTML5标准，基于此，本协议定义了另外一系列事件，用于给移动端更广泛的支持 设备传感器事件和方法都在mraid协议基础上直接增加，不产生新的命名空间，由mraid.addEventListener(事件, 处理方法)监听。

事件列表

• shake

  “shake” -> function()
  参数：
  • none
  经由触发：
  • 手机摇动触发

• tiltChange

  “tiltChange” -> function(x,y,z)
  参数：
  • x,y,z分别为对应轴的浮点型旋转向量
  经由触发：
  • 手机倾斜角度变化时触发

• headingChange

  “headingChange” -> function(heading)
  参数：
  • heading 取值为0-360整数角度，0为正北方向，顺时针累加
  经由触发：
  • 手机朝向变化触发

• locationChange

  “locationChange” -> function(lat,lng,acc)
  参数：
  均为浮点数
  • lat为经度
  • lng为纬度
  • acc为精确度
  经由触发：
  • 手机地理位置变化触发

• networkChange

  “networkChange” -> function(network)
  参数：
  • network - String 取值为unknown，offline，cell，wifi
  经由触发：
  • 手机网络状态变化触发

• orientationChange
  “orientationChange” -> function(angle)
  参数：
  • Angle为角度，90为竖屏，180为横屏
  经由触发：
  • 手机横竖屏变化触发

方法

• 
  
• supports 方法
  supports方法允许广告询问设备支持的指定功能。该方法是对mraid.supports()进行拓展，取值为shake、title、heading、keyboard、location、network、orientation。
  

supports(feature) -> Boolean
参数：
• String 要检测特性的名称（shake、title、heading、keyboard、location、network、orientation）
return values:
• Boolean
true —— 支持该功能，并且getter和事件都是可用的。
false —— 当前设备不支持本功能。

获取本协议版本

• 
  
• caamraid.getVersion方法
  

getVersion() -> String
参数：
• none
返回值
• String – 本协议的版本号，getVersion()将返回“1.0”

超出范围

从广告服务器，广告网络，本地资源检索广告
广告尺寸
为缓存或离线下载资源到本地文件系统
IDE集成
安全及隐私
国际化
错误报告

可扩展性和兼容性

最小支持支持MRAID2.0