3.02017-07current
MRAID_ENV 初始化、exposureChange 可见性、可听性度量、open()/unload()、方向控制与定位、VPAID 集成附录
MRAID section navigation
MRAID
3.0 · currentMRAID (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,video}.api declares the supported API frameworks (AdCOM APIFrameworks: 3 = MRAID 1.0, 5 = MRAID 2.0, 6 = MRAID 3.0).
30 methods · 7 events · 5 states · 6 device features
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.
How it works: the container–creative contract
MRAID defines the JS API contract between the container (SDK / WebView host) and the HTML5 creative: the container injects a unified mraid object, and the creative drives ad behavior and senses state through event subscriptions and method calls — the same creative behaves consistently across MRAID-enabled apps. It targets in-app interstitial and expanding rich-media ads; VAST carries the video delivery chain while MRAID carries the interactive layer inside the creative.
- Container side · SDK / WebView hostInjects mraid.js and the mraid object before the creative loads; 3.0 also requires setting the global MRAID_ENV first. Executes state transitions (the container-side effect of expand/collapse/resize/close), provides the host close control, and reports viewability, exposure and audio volume changes to the creative via events.
- Creative side · HTML5 creativeWaits for ready before calling the API; queries state and position via get*; checks device features with supports() before use; drives ad behavior with set*Properties plus expand()/resize()/open()/close(), and subscribes to events via addEventListener.
Four contract points
- The mraid object is injected by the container — creatives must not ship their own mraid implementation; the on-site HTML5 Ad Tools sandbox injects a same-name implementation for testing.
- MRAID_ENV (3.0) — the container must set it before mraid.js loads; the creative uses it to detect the MRAID environment at initialization and read version/vendor/supports/placementType.
- ready timing — API calls before the ready event (or while state is still loading) are illegal; creatives should defer initialization until after ready.
- Check before use — device features (sms/tel/calendar/storePicture/inlineVideo/location) must be probed with supports() first; fall back to open() or similar when unsupported.
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.
State transitions
Compiled from the state/method descriptions in the data layer; resize() is illegal from the expanded state. For the full transition diagram (including details such as resized → expanded), the official PDF state-machine figure prevails.
| From | To | Trigger | Notes |
|---|---|---|---|
| loading | default | ready | inline first display; a preloaded interstitial stays here or moves to hidden |
| hidden | default | host display | interstitial only: shown by the host; inline ads never enter hidden |
| default | expanded | expand() | enlarges/fullscreens per expandProperties; host shows a close control unless useCustomClose applies |
| expanded | default | collapse() / close() | reverts to the original size and position |
| default | resized | resize() | resizes per resizeProperties; may go partially offscreen with allowOffscreen; illegal from expanded |
| resized | default | collapse() / close() | reverts to the original size and position |
| default | hidden | close() | interstitial only: closed by the ad; the webview persists but is not visible |
Versions
2.02013-04legacy
resized 状态与 resize()、sizeChange 事件、storePicture/createCalendarEvent/inlineVideo、two-part 创意
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)
Content faithfully follows the IAB Tech Lab MRAID 3.0 official spec (CC-BY 3.0); spec data is in the original English, translations are machine-generated first drafts (draft). · API reference · Version changes