3.02017-07current
MRAID_ENV 初始化、exposureChange 可见性、可听性度量、open()/unload()、方向控制与定位、VPAID 集成附录
MRAID (Mobile Rich Media Ad Interface Definitions) is IAB Tech Lab's container and event standard for in-app rich media / playable creatives: the SDK webview injects a unified API so creatives can expand, resize, open external links and sense viewability/audibility. 3.0 is the current version, 2.0 the legacy baseline; in OpenRTB, imp.banner.api=3 marks a MRAID-capable placement.
30 methods · 7 events · 5 states · 6 device features
Data status: manual curation (first-draft). The official spec has no machine-readable source; where this differs from the official text, the official PDF prevails. See data/mraid-spec/PROVENANCE.json.
Data sources & baseline
The official spec is PDF-only (no machine-readable source): on-site data is a manual curation checked against the official PDF, with key facts cross-checked against the Google Mobile Ads SDK MRAID docs · fetched 2026-08-31 · CC-BY 3.0 (IAB Tech Lab)
Versions
2.02013-04legacy
resized 状态与 resize()、sizeChange 事件、storePicture/createCalendarEvent/inlineVideo、two-part 创意
Ad states
- 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.
Events
| Name | Params | Since | Description |
|---|---|---|---|
| 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. |
| viewableChangedeprecated in 3.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. |
Methods
| Name | Category | Returns | Since | Description |
|---|---|---|---|---|
| getVersion() | Information | String | 1.0 | Returns the MRAID version supported by the host. 3.0 hosts return "3.0". |
| getVendor() | Information | String | 3.0 | Returns a vendor identifier for the MRAID implementation (SDK/ad platform), useful for diagnostics. |
| getState() | Information | String | 1.0 | Returns the current ad state: loading, default, expanded, resized or hidden. |
| getPlacementType() | Information | String | 1.0 | Returns "inline" or "interstitial" as configured by the host for this ad. |
| isViewable()deprecated in 3.0 | Information | Boolean | 2.0 | Returns whether the webview is currently visible. Deprecated in 3.0: kept only for compatibility, superseded by the exposureChange event. |
| supports() | Information | 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() | Position & size | {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() | Position & size | {x,y} | 1.0 | Returns the position of the ad container in its initial state, in device-independent pixels relative to the screen. |
| getCurrentPosition() | Position & size | {x,y,width,height} | 1.0 | Returns the current position and size of the ad container, relative to the screen origin. |
| getMaxSize() | Position & size | {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() | Properties | {width,height,useCustomClose,isModal} | 1.0 | Returns the current expand properties used by expand(). |
| setExpandProperties() | Properties | void | 1.0 | Sets expand properties: width/height of the expanded ad, useCustomClose (2.x) and isModal. Hosts may clamp to maxSize. |
| getResizeProperties() | Properties | {width,height,offsetX,offsetY,customClosePosition,allowOffscreen} | 2.0 | Returns the current resize properties used by resize(). |
| setResizeProperties() | Properties | void | 2.0 | Sets resize properties: target width/height, offset from the current container, customClosePosition (top-left … center) and allowOffscreen. |
| getOrientationProperties() | Properties | {allowOrientationChange,forceOrientation,customClosePosition} | 3.0 | Returns the orientation properties controlling device rotation while the ad runs. |
| setOrientationProperties() | Properties | void | 3.0 | Sets orientation behavior: allowOrientationChange (bool), forceOrientation (portrait/landscape/none) and customClosePosition. |
| getCurrentAppOrientation() | Information | {orientation,locked} | 3.0 | Returns the current app orientation (portrait/landscape) and whether it is locked by the app. |
| getLocation() | Information | {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() | Events | void | 1.0 | Registers a listener for a MRAID event (ready, error, stateChange, sizeChange, exposureChange, audioVolumeChange, …). |
| removeEventListener() | Events | void | 1.0 | Removes a previously registered listener; with a single argument removes all listeners for the event. |
| expand() | Actions | 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() | Actions | void | 1.0 | Reverts an expanded/resized ad to default, or hides an interstitial (moving it to hidden). |
| resize() | Actions | void | 2.0 | Resizes the ad container per resizeProperties; may move the ad partially offscreen when allowOffscreen is true. Illegal from expanded state. |
| open() | Actions | 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()deprecated in 3.0 | Actions | void | 2.0 | Plays a video via the host's video player. Deprecated in 3.0: use open() instead. |
| storePicture() | Actions | 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() | Actions | 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() | Actions | 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()deprecated in 3.0 | Actions | 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 appendix | 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 environment detection)
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 features & property shapes
- 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 changes
| Target | Description |
|---|---|
| AddedMRAID_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. |
| AddedexposureChange | Exposure percentage, visible rectangle and occlusion rectangles — the correct basis for viewability measurement. |
| AddedaudioVolumeChange | Audibility measurement: volume changes delivered to the ad. |
| Addedopen | Open URLs / deep links outside the ad (external browser, in-app browser, other apps). |
| Addedunload | Graceful self-unload and host notification for broken or unwanted ads. |
| AddedsetOrientationProperties | Control device orientation behavior (with getOrientationProperties). |
| AddedgetCurrentAppOrientation | Read the current app orientation and lock state. |
| AddedgetLocation | Device location access behind the location supports feature. |
| AddedinitVpaid | VPAID appendix integrated: optional host bridge for MRAID+VPAID creatives. |
| DeprecatedisViewable | Kept for compatibility; superseded by exposureChange. |
| DeprecatedviewableChange | Superseded by exposureChange. |
| DeprecateduseCustomClose | Hosts always provide the close control; customClosePosition governs placement. |
| DeprecatedplayVideo | Use open() instead. |
| Deprecatedexpand(url) | Two-part creatives remain compatible but new 3.0 features do not support them. |
| Changedinitialization | Explicit guidance for pre-loading and ad readiness: hosts detect ad readiness before showing interstitials, avoiding blank-screen experiences. |