ORTB
…
MRAID 分册导航

MRAID

3.0 · current

MRAID（Mobile Rich Media Ad Interface Definitions）是 IAB Tech Lab 为应用内富媒体/可玩创意定义的容器与事件标准：SDK webview 注入统一 API，创意据此展开、缩放、打开外链并感知可见性/可听性。3.0 为现行版本，2.0 为存量基线；OpenRTB 中经 imp.{banner,video}.api 声明支持的 API 框架（AdCOM APIFrameworks：3 = MRAID 1.0、5 = MRAID 2.0、6 = MRAID 3.0）。

30 方法 · 7 事件 · 5 状态 · 6 设备特性

本页目录
数据状态：人工整理稿（first-draft）。官方无机器可读源，与官方原文如有出入以官方 PDF 为准；溯源见 data/mraid-spec/PROVENANCE.json。

状态、事件、方法、环境字段与设备特性描述为机器生成初稿译文（draft），英文原文可通过上方中英对照开关查看。

运行机制：容器与创意的契约

MRAID 规定容器（SDK / WebView 宿主）与 HTML5 创意之间的 JS API 契约：容器注入统一 mraid 对象，创意以事件订阅与方法调用驱动广告行为并感知状态；同一创意在不同支持 MRAID 的应用中行为一致。适用场景为应用内插屏（interstitial）与可展开（expanding）富媒体广告；视频投放链路由 VAST 承载，创意内交互层由 MRAID 承载。

  • 容器侧 · SDK / WebView 宿主在创意加载前注入 mraid.js 与 mraid 对象；3.0 还须先设置全局 MRAID_ENV。负责执行状态迁移（expand/collapse/resize/close 的容器侧效果）、提供宿主关闭控件，并以事件向创意报告可见性、曝光与音量变化。
  • 创意侧 · HTML5 创意等待 ready 后再调用 API；以 get* 查询状态与位置；以 supports() 检测设备能力后使用；以 set*Properties 配合 expand()/resize()/open()/close() 驱动广告行为，并用 addEventListener 订阅事件。

四个契约要点

  1. mraid 对象由容器注入——创意不应自带 mraid 实现；站内 HTML5 Ad Tools 沙箱注入同名实现供实测。
  2. MRAID_ENV（3.0）——容器须在 mraid.js 加载前设置；创意据此在初始化期判断是否处于 MRAID 环境，并读取 version/vendor/supports/placementType 等。
  3. ready 时序——ready 事件前（或 state 仍为 loading 时）调用 API 不合法；创意应把初始化逻辑推迟到 ready 之后。
  4. 能力先检后用——调用 sms/tel/calendar/storePicture/inlineVideo/location 等设备能力前须经 supports() 检查，不支持时回退 open() 等替代方案。

广告状态

  • loading

    广告被请求后、可交互前的初始状态；离开时触发 ready 事件。预载但未展示的插屏广告停留于此或转入 hidden。ENInitial 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

    广告以原始尺寸与位置放置在页面上（inline）或全屏展示（interstitial）。ENThe ad is placed with its original size and position on the page (inline) or shown fullscreen (interstitial).译稿校对中

  • expanded

    广告已通过 expand() 放大或全屏；容器可能覆盖整个屏幕，宿主提供关闭控件（useCustomClose 适用时除外）。ENThe 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

    广告容器已通过 resize() 调整尺寸/位置；按 allowOffscreen 广告可部分出屏。ENThe ad container has been resized/repositioned via resize(); the ad may be partially offscreen per allowOffscreen.译稿校对中

  • hidden

    已关闭或尚未展示的插屏广告；webview 保留但不可见。inline 广告不会进入 hidden。ENAn interstitial that has been closed or not yet displayed; the webview persists but is not visible. Inline ads never enter hidden.译稿校对中

状态机迁移

下表按数据层中状态/方法的描述整理；resize() 不可在 expanded 状态调用。完整迁移图（含 resized → expanded 等细节）以官方 PDF 状态机图为准。

起始状态目标状态触发说明
loadingdefaultreadyinline 首次展示；插屏预载未展示时停留于此或转入 hidden
hiddendefaulthost display仅 interstitial：被宿主展示时转入 default；inline 广告不会进入 hidden
defaultexpandedexpand()按 expandProperties 扩大或全屏；宿主提供关闭控件（useCustomClose 适用时除外）
expandeddefaultcollapse() / close()回到原始尺寸与位置
defaultresizedresize()按 resizeProperties 调整容器，allowOffscreen 时可部分出屏；expanded 状态下不可调用
resizeddefaultcollapse() / close()回到原始尺寸与位置
defaulthiddenclose()仅 interstitial：被关闭后转入 hidden；webview 保留但不可见

版本

3.02017-07current

MRAID_ENV 初始化、exposureChange 可见性、可听性度量、open()/unload()、方向控制与定位、VPAID 集成附录译稿校对中

2.02013-04legacy

resized 状态与 resize()、sizeChange 事件、storePicture/createCalendarEvent/inlineVideo、two-part 创意译稿校对中

数据源与基线

官方规范仅 PDF（无机器可读源）：站内数据为对照官方 PDF 的人工整理稿，关键事实经 Google Mobile Ads SDK MRAID 文档交叉核对 · 采集 2026-08-31 · CC-BY 3.0 (IAB Tech Lab)

IAB MRAID 规范入口 ↗

内容忠实于 IAB Tech Lab MRAID 3.0 官方规范（CC-BY 3.0）；规范收录数据为英文原文，译文为机器生成初稿（draft）。 · API 参考 · 版本变更