3.02017-07current
MRAID_ENV 初始化、exposureChange 可见性、可听性度量、open()/unload()、方向控制与定位、VPAID 集成附录
MRAID（Mobile Rich Media Ad Interface Definitions）是 IAB Tech Lab 为应用内富媒体/可玩创意定义的容器与事件标准：SDK webview 注入统一 API，创意据此展开、缩放、打开外链并感知可见性/可听性。3.0 为现行版本，2.0 为存量基线；OpenRTB 中 imp.banner.api=3 即表示广告位支持 MRAID。
30 方法 · 7 事件 · 5 状态 · 6 设备特性
数据状态：人工整理稿（first-draft）。官方无机器可读源，与官方原文如有出入以官方 PDF 为准；溯源见 data/mraid-spec/PROVENANCE.json。
数据源与基线
官方规范仅 PDF（无机器可读源）：站内数据为对照官方 PDF 的人工整理稿，关键事实经 Google Mobile Ads SDK MRAID 文档交叉核对 · 采集 2026-08-31 · CC-BY 3.0 (IAB Tech Lab)
版本
2.02013-04legacy
resized 状态与 resize()、sizeChange 事件、storePicture/createCalendarEvent/inlineVideo、two-part 创意
广告状态
- loading
Initial state after the ad is requested and before it is ready to interact; the ready event fires when leaving it. An interstitial that is pre-loaded but not shown stays here or moves to hidden.
- default
The ad is placed with its original size and position on the page (inline) or shown fullscreen (interstitial).
- expanded
The ad has enlarged or gone fullscreen via expand(); the container may cover the whole screen and the host shows a close control unless useCustomClose applies.
- resized
The ad container has been resized/repositioned via resize(); the ad may be partially offscreen per allowOffscreen.
- hidden
An interstitial that has been closed or not yet displayed; the webview persists but is not visible. Inline ads never enter hidden.
事件
| 名称 | 参数 | 起始版本 | 描述 |
|---|---|---|---|
| ready | none | 1.0 | Fired when the ad leaves the loading state. Only after ready may the ad rely on properties like screenSize/maxSize and display content; interstitials should wait for it before showing interactive elements. |
| error | message, action | 1.0 | Fired when a method fails: message is a human-readable reason, action is the name of the failed method (e.g. storePicture). |
| stateChange | state | 1.0 | Fired whenever the ad state changes; the single argument is the new state (default / expanded / resized / hidden). |
| sizeChange | width, height | 2.0 | Fired when the ad container size changes (in pixels), allowing the ad to reflow its layout. |
| viewableChange3.0 起废弃 | viewable | 2.0 | Boolean hint whether the webview is visible. Deprecated in 3.0: viewability must account for exposure percentage and occlusion — use exposureChange instead. |
| exposureChange | exposedPercentage, visibleRectangle, occlusionRectangles | 3.0 | Fired when the ad exposure changes: exposedPercentage (0.0–100.0), visibleRectangle {x,y,width,height} in the ad's coordinate space, and occlusionRectangles describing covering elements. Replaces viewableChange/isViewable for viewability. |
| audioVolumeChange | volumePercentage | 3.0 | Fired when the audible volume available to the ad changes; volumePercentage is 0.0 (muted) to 100.0. Enables audibility measurement for video/audio creatives. |
方法
| 名称 | 分类 | 返回 | 起始版本 | 描述 |
|---|---|---|---|---|
| getVersion() | 信息查询 | String | 1.0 | Returns the MRAID version supported by the host. 3.0 hosts return "3.0". |
| getVendor() | 信息查询 | String | 3.0 | Returns a vendor identifier for the MRAID implementation (SDK/ad platform), useful for diagnostics. |
| getState() | 信息查询 | String | 1.0 | Returns the current ad state: loading, default, expanded, resized or hidden. |
| getPlacementType() | 信息查询 | String | 1.0 | Returns "inline" or "interstitial" as configured by the host for this ad. |
| isViewable()3.0 起废弃 | 信息查询 | Boolean | 2.0 | Returns whether the webview is currently visible. Deprecated in 3.0: kept only for compatibility, superseded by the exposureChange event. |
| supports() | 信息查询 | Boolean | 1.0 | Tests a device/host feature: sms, tel, calendar, storePicture, inlineVideo, and (3.0) location. Ads must check before calling the matching feature method. |
| getScreenSize() | 位置与尺寸 | {width,height} | 1.0 | Returns the current device screen size in pixels. In 3.0 the value is not guaranteed until the ready event has fired. |
| getDefaultPosition() | 位置与尺寸 | {x,y} | 1.0 | Returns the position of the ad container in its initial state, in device-independent pixels relative to the screen. |
| getCurrentPosition() | 位置与尺寸 | {x,y,width,height} | 1.0 | Returns the current position and size of the ad container, relative to the screen origin. |
| getMaxSize() | 位置与尺寸 | {width,height} | 1.0 | Returns the maximum size the ad may expand or resize to (excluding host UI such as the close indicator). Not guaranteed until ready in 3.0. |
| getExpandProperties() | 属性设置 | {width,height,useCustomClose,isModal} | 1.0 | Returns the current expand properties used by expand(). |
| setExpandProperties() | 属性设置 | void | 1.0 | Sets expand properties: width/height of the expanded ad, useCustomClose (2.x) and isModal. Hosts may clamp to maxSize. |
| getResizeProperties() | 属性设置 | {width,height,offsetX,offsetY,customClosePosition,allowOffscreen} | 2.0 | Returns the current resize properties used by resize(). |
| setResizeProperties() | 属性设置 | void | 2.0 | Sets resize properties: target width/height, offset from the current container, customClosePosition (top-left … center) and allowOffscreen. |
| getOrientationProperties() | 属性设置 | {allowOrientationChange,forceOrientation,customClosePosition} | 3.0 | Returns the orientation properties controlling device rotation while the ad runs. |
| setOrientationProperties() | 属性设置 | void | 3.0 | Sets orientation behavior: allowOrientationChange (bool), forceOrientation (portrait/landscape/none) and customClosePosition. |
| getCurrentAppOrientation() | 信息查询 | {orientation,locked} | 3.0 | Returns the current app orientation (portrait/landscape) and whether it is locked by the app. |
| getLocation() | 信息查询 | {lat,lon,type,accuracy} | 3.0 | Returns the device location when supported (supports("location") is true) and permitted: lat/lon in decimal degrees, type (gps/ip/user-provided) and accuracy in meters. |
| addEventListener() | 事件订阅 | void | 1.0 | Registers a listener for a MRAID event (ready, error, stateChange, sizeChange, exposureChange, audioVolumeChange, …). |
| removeEventListener() | 事件订阅 | void | 1.0 | Removes a previously registered listener; with a single argument removes all listeners for the event. |
| expand() | 动作执行 | void | 1.0 | Expands the ad per expandProperties. The optional url argument (two-part creative) is deprecated in 3.0 — use a single-part creative; two-part ads remain supported for compatibility only. |
| close() | 动作执行 | void | 1.0 | Reverts an expanded/resized ad to default, or hides an interstitial (moving it to hidden). |
| resize() | 动作执行 | void | 2.0 | Resizes the ad container per resizeProperties; may move the ad partially offscreen when allowOffscreen is true. Illegal from expanded state. |
| open() | 动作执行 | void | 3.0 | Opens a URL outside the ad: external browser, in-app browser, or a deep link to another app (e.g. app store). The 3.0 replacement for the deprecated expand(url)/playVideo(url) usages. |
| playVideo()3.0 起废弃 | 动作执行 | void | 2.0 | Plays a video via the host's video player. Deprecated in 3.0: use open() instead. |
| storePicture() | 动作执行 | void | 2.0 | Stores an image (by URL) in the device's media gallery. Requires supports("storePicture"); the host must confirm with the user. |
| createCalendarEvent() | 动作执行 | void | 2.0 | Creates a calendar event from a W3C CalendarEvent-like parameter object. Requires supports("calendar"); the host must confirm with the user. Failure fires error with action createCalendarEvent. |
| unload() | 动作执行 | void | 3.0 | Lets the ad gracefully unload itself (e.g. when it cannot render correctly) and notifies the host to close the webview; intended for pre-loaded interstitials and error recovery. |
| useCustomClose()3.0 起废弃 | 动作执行 | void | 2.0 | Switches whether the ad supplies its own close control instead of the host's. Deprecated in 3.0: expanded/interstitial containers always show a host close control; customClosePosition governs it instead. |
| initVpaid() | VPAID 附录 | vpaidObject | 3.0 | VPAID integration appendix: hands a VPAID ad object to the MRAID host, returning an object exposing subscribe/unsubscribe, startAd, getAdDuration, getAdRemainingTime and VPAID event relay (AdClickThru, AdPause, AdPlaying…). Optional host support for creatives mixing MRAID and VPAID. |
MRAID_ENV（3.0 环境检测）
3.0 requires the host to set the global MRAID_ENV object before mraid.js loads, so the ad can detect the MRAID environment and read environment details immediately during initialization.
| MRAID_ENV.version | MRAID version supported by the host (e.g. "3.0"). |
| MRAID_ENV.vendor | Vendor identifier of the MRAID implementation. |
| MRAID_ENV.supports | Feature map: sms, tel, calendar, storePicture, inlineVideo, location. |
| MRAID_ENV.placementType | "inline" or "interstitial". |
| MRAID_ENV.currentPosition | Initial position/size of the ad container {x,y,width,height}. |
| MRAID_ENV.maxSize | Maximum ad size {width,height} available to the ad. |
| MRAID_ENV.screenSize | Device screen size {width,height}. |
supports 设备特性与属性形状
- sms1.0+
Sending SMS messages.
- tel1.0+
Placing phone calls.
- calendar2.0+
Adding calendar events (createCalendarEvent).
- storePicture2.0+
Storing images in the media gallery (storePicture).
- inlineVideo2.0+
Playing inline video without leaving the ad.
- location3.0+
Accessing device location (getLocation).
expandProperties
- width: Number
- height: Number
- useCustomClose: Boolean
- isModal: Boolean
resizeProperties
- width: Number
- height: Number
- offsetX: Number
- offsetY: Number
- customClosePosition: String
- allowOffscreen: Boolean
orientationProperties
- allowOrientationChange: Boolean
- forceOrientation: portrait|landscape|none
- customClosePosition: String
2.0 → 3.0 变更
| 对象 | 描述 |
|---|---|
| 新增MRAID_ENV | Host-provided global object with environment details (version, vendor, supports, placementType, positions, sizes), set before mraid.js loads — reliable MRAID detection and early initialization. |
| 新增exposureChange | Exposure percentage, visible rectangle and occlusion rectangles — the correct basis for viewability measurement. |
| 新增audioVolumeChange | Audibility measurement: volume changes delivered to the ad. |
| 新增open | Open URLs / deep links outside the ad (external browser, in-app browser, other apps). |
| 新增unload | Graceful self-unload and host notification for broken or unwanted ads. |
| 新增setOrientationProperties | Control device orientation behavior (with getOrientationProperties). |
| 新增getCurrentAppOrientation | Read the current app orientation and lock state. |
| 新增getLocation | Device location access behind the location supports feature. |
| 新增initVpaid | VPAID appendix integrated: optional host bridge for MRAID+VPAID creatives. |
| 废弃isViewable | Kept for compatibility; superseded by exposureChange. |
| 废弃viewableChange | Superseded by exposureChange. |
| 废弃useCustomClose | Hosts always provide the close control; customClosePosition governs placement. |
| 废弃playVideo | Use open() instead. |
| 废弃expand(url) | Two-part creatives remain compatible but new 3.0 features do not support them. |
| 变更initialization | Explicit guidance for pre-loading and ad readiness: hosts detect ad readiness before showing interstitials, avoiding blank-screen experiences. |