MRAID section navigation
API reference3.0
On this page
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.
Events
Lifecycle & state
| 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. |
Observation (viewability / exposure / audio)
| Name | Params | Since | Description |
|---|---|---|---|
| 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
Information8
| Name | Returns | Since | Description |
|---|---|---|---|
| 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()deprecated in 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. |
| 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. |
Position & size4
| Name | Returns | Since | Description |
|---|---|---|---|
| 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. |
Properties6
| Name | Returns | Since | Description |
|---|---|---|---|
| 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. |
Events2
| Name | Returns | Since | Description |
|---|---|---|---|
| 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. |
Actions9
| Name | Returns | Since | Description |
|---|---|---|---|
| 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()deprecated in 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()deprecated in 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. |
VPAID appendix1
| Name | Returns | Since | Description |
|---|---|---|---|
| initVpaid() | 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