MRAID 分册导航
API 参考3.0
数据状态：人工整理稿（first-draft）。官方无机器可读源，与官方原文如有出入以官方 PDF 为准；溯源见 data/mraid-spec/PROVENANCE.json。
状态、事件、方法、环境字段与设备特性描述为机器生成初稿译文（draft），英文原文可通过上方中英对照开关查看。
事件
生命周期与状态
| 名称 | 参数 | 起始版本 | 描述 |
|---|---|---|---|
| ready | none | 1.0 | 广告离开 loading 状态时触发。只有 ready 之后广告才能依赖 screenSize/maxSize 等属性并展示内容；插屏广告应在 ready 后再展示交互元素。ENFired 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 | 方法执行失败时触发：message 为人类可读的失败原因，action 为失败方法名（如 storePicture）。ENFired 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 | 广告状态变化时触发；唯一参数为新状态（default / expanded / resized / hidden）。ENFired whenever the ad state changes; the single argument is the new state (default / expanded / resized / hidden).译稿校对中 |
| sizeChange | width, height | 2.0 | 广告容器尺寸变化（像素）时触发，供广告重新排版布局。ENFired when the ad container size changes (in pixels), allowing the ad to reflow its layout.译稿校对中 |
观测类（可见 / 曝光 / 音量）
| 名称 | 参数 | 起始版本 | 描述 |
|---|---|---|---|
| viewableChange3.0 起废弃 | viewable | 2.0 | webview 是否可见的布尔提示。3.0 起废弃：可见性须计入曝光百分比与遮挡——改用 exposureChange。ENBoolean 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 | 广告曝光变化时触发：exposedPercentage（0.0–100.0）、visibleRectangle {x,y,width,height}（广告坐标系）与描述遮挡元素的 occlusionRectangles。替代 viewableChange/isViewable 承担可见性度量。ENFired 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 | 广告可用的音量变化时触发；volumePercentage 为 0.0（静音）到 100.0。为视频/音频创意提供可听性度量。ENFired when the audible volume available to the ad changes; volumePercentage is 0.0 (muted) to 100.0. Enables audibility measurement for video/audio creatives.译稿校对中 |
方法
信息查询8
| 名称 | 返回 | 起始版本 | 描述 |
|---|---|---|---|
| getVersion() | String | 1.0 | 返回宿主支持的 MRAID 版本。3.0 宿主返回 "3.0"。ENReturns the MRAID version supported by the host. 3.0 hosts return "3.0".译稿校对中 |
| getVendor() | String | 3.0 | 返回 MRAID 实现的厂商标识（SDK/广告平台），用于诊断。ENReturns a vendor identifier for the MRAID implementation (SDK/ad platform), useful for diagnostics.译稿校对中 |
| getState() | String | 1.0 | 返回当前广告状态：loading、default、expanded、resized 或 hidden。ENReturns the current ad state: loading, default, expanded, resized or hidden.译稿校对中 |
| getPlacementType() | String | 1.0 | 返回宿主为本广告配置的 "inline" 或 "interstitial"。ENReturns "inline" or "interstitial" as configured by the host for this ad.译稿校对中 |
| isViewable()3.0 起废弃 | Boolean | 2.0 | 返回 webview 当前是否可见。3.0 起废弃：仅为兼容保留，已被 exposureChange 事件取代。ENReturns whether the webview is currently visible. Deprecated in 3.0: kept only for compatibility, superseded by the exposureChange event.译稿校对中 |
| supports() | Boolean | 1.0 | 检测设备/宿主特性：sms、tel、calendar、storePicture、inlineVideo 及 3.0 的 location。广告在调用对应特性方法前须先检查。ENTests 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 | 返回当前应用方向（portrait/landscape）及是否被应用锁定。ENReturns the current app orientation (portrait/landscape) and whether it is locked by the app.译稿校对中 |
| getLocation() | {lat,lon,type,accuracy} | 3.0 | 在支持（supports("location") 为 true）且被允许时返回设备位置：lat/lon 为十进制度数，type（gps/ip/user-provided）与 accuracy（米）。ENReturns 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.译稿校对中 |
位置与尺寸4
| 名称 | 返回 | 起始版本 | 描述 |
|---|---|---|---|
| getScreenSize() | {width,height} | 1.0 | 返回当前设备屏幕尺寸（像素）。3.0 中该值在 ready 事件触发前不保证有效。ENReturns 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 | 返回广告容器初始状态下的位置，单位为相对于屏幕的设备无关像素。ENReturns 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 | 返回广告容器当前位置与尺寸，相对于屏幕原点。ENReturns the current position and size of the ad container, relative to the screen origin.译稿校对中 |
| getMaxSize() | {width,height} | 1.0 | 返回广告可展开或调整到的最大尺寸（不含宿主 UI 如关闭指示器）。3.0 中 ready 前不保证有效。ENReturns 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.译稿校对中 |
属性设置6
| 名称 | 返回 | 起始版本 | 描述 |
|---|---|---|---|
| getExpandProperties() | {width,height,useCustomClose,isModal} | 1.0 | 返回 expand() 使用的当前展开属性。ENReturns the current expand properties used by expand().译稿校对中 |
| setExpandProperties() | void | 1.0 | 设置展开属性：展开后广告的 width/height、useCustomClose（2.x）与 isModal。宿主可能将其裁剪到 maxSize。ENSets 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 | 返回 resize() 使用的当前调整属性。ENReturns the current resize properties used by resize().译稿校对中 |
| setResizeProperties() | void | 2.0 | 设置调整属性：目标 width/height、相对当前容器的偏移、customClosePosition（top-left … center）与 allowOffscreen。ENSets resize properties: target width/height, offset from the current container, customClosePosition (top-left … center) and allowOffscreen.译稿校对中 |
| getOrientationProperties() | {allowOrientationChange,forceOrientation,customClosePosition} | 3.0 | 返回控制广告运行期间设备旋转的方向属性。ENReturns the orientation properties controlling device rotation while the ad runs.译稿校对中 |
| setOrientationProperties() | void | 3.0 | 设置方向行为：allowOrientationChange（布尔）、forceOrientation（portrait/landscape/none）与 customClosePosition。ENSets orientation behavior: allowOrientationChange (bool), forceOrientation (portrait/landscape/none) and customClosePosition.译稿校对中 |
事件订阅2
| 名称 | 返回 | 起始版本 | 描述 |
|---|---|---|---|
| addEventListener() | void | 1.0 | 注册 MRAID 事件监听器（ready、error、stateChange、sizeChange、exposureChange、audioVolumeChange 等）。ENRegisters a listener for a MRAID event (ready, error, stateChange, sizeChange, exposureChange, audioVolumeChange, …).译稿校对中 |
| removeEventListener() | void | 1.0 | 移除先前注册的监听器；传单一参数时移除该事件的全部监听器。ENRemoves a previously registered listener; with a single argument removes all listeners for the event.译稿校对中 |
动作执行9
| 名称 | 返回 | 起始版本 | 描述 |
|---|---|---|---|
| expand() | void | 1.0 | 按 expandProperties 展开广告。可选的 url 参数（two-part 创意）在 3.0 中废弃——改用 single-part 创意；two-part 广告仅为兼容保留。ENExpands 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 | 将 expanded/resized 的广告恢复到 default，或隐藏插屏广告（转入 hidden）。ENReverts an expanded/resized ad to default, or hides an interstitial (moving it to hidden).译稿校对中 |
| resize() | void | 2.0 | 按 resizeProperties 调整广告容器；allowOffscreen 为 true 时广告可部分出屏。不可在 expanded 状态调用。ENResizes the ad container per resizeProperties; may move the ad partially offscreen when allowOffscreen is true. Illegal from expanded state.译稿校对中 |
| open() | void | 3.0 | 在广告外打开 URL：外部浏览器、应用内浏览器或深度链接到其他应用（如应用商店）。3.0 中替代废弃的 expand(url)/playVideo(url) 用法。ENOpens 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 | 通过宿主的视频播放器播放视频。3.0 起废弃：改用 open()。ENPlays a video via the host's video player. Deprecated in 3.0: use open() instead.译稿校对中 |
| storePicture() | void | 2.0 | 将图片（按 URL）存储到设备媒体库。须 supports("storePicture")；宿主须向用户确认。ENStores an image (by URL) in the device's media gallery. Requires supports("storePicture"); the host must confirm with the user.译稿校对中 |
| createCalendarEvent() | void | 2.0 | 按 W3C CalendarEvent 风格的参数对象创建日历事件。须 supports("calendar")；宿主须向用户确认。失败时触发 error，action 为 createCalendarEvent。ENCreates 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 | 广告优雅地卸载自身（如无法正确渲染时）并通知宿主关闭 webview；用于预载插屏与错误恢复。ENLets 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 | 切换广告是否自行提供关闭控件而非使用宿主的。3.0 起废弃：expanded/interstitial 容器始终显示宿主关闭控件；customClosePosition 控制其位置。ENSwitches 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 附录1
| 名称 | 返回 | 起始版本 | 描述 |
|---|---|---|---|
| initVpaid() | vpaidObject | 3.0 | VPAID 集成附录：将 VPAID 广告对象交给 MRAID 宿主，返回暴露 subscribe/unsubscribe、startAd、getAdDuration、getAdRemainingTime 与 VPAID 事件中继（AdClickThru、AdPause、AdPlaying…）的对象。面向混合 MRAID 与 VPAID 创意的可选宿主支持。ENVPAID 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 要求宿主在 mraid.js 加载前设置全局 MRAID_ENV 对象，以便广告在初始化期即可检测 MRAID 环境并读取环境信息。EN3.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 版本（如 "3.0"）。ENMRAID version supported by the host (e.g. "3.0").译稿校对中 |
| MRAID_ENV.vendor | MRAID 实现的厂商标识。ENVendor identifier of the MRAID implementation.译稿校对中 |
| MRAID_ENV.supports | 特性映射：sms、tel、calendar、storePicture、inlineVideo、location。ENFeature map: sms, tel, calendar, storePicture, inlineVideo, location.译稿校对中 |
| MRAID_ENV.placementType | "inline" 或 "interstitial"。EN"inline" or "interstitial".译稿校对中 |
| MRAID_ENV.currentPosition | 广告容器初始位置/尺寸 {x,y,width,height}。ENInitial position/size of the ad container {x,y,width,height}.译稿校对中 |
| MRAID_ENV.maxSize | 广告可用的最大尺寸 {width,height}。ENMaximum ad size {width,height} available to the ad.译稿校对中 |
| MRAID_ENV.screenSize | 设备屏幕尺寸 {width,height}。ENDevice screen size {width,height}.译稿校对中 |
supports 设备特性与属性形状
- sms1.0+
发送短信。ENSending SMS messages.译稿校对中
- tel1.0+
拨打电话。ENPlacing phone calls.译稿校对中
- calendar2.0+
添加日历事件（createCalendarEvent）。ENAdding calendar events (createCalendarEvent).译稿校对中
- storePicture2.0+
将图片存储到媒体库（storePicture）。ENStoring images in the media gallery (storePicture).译稿校对中
- inlineVideo2.0+
在广告内播放内联视频而不离开广告。ENPlaying inline video without leaving the ad.译稿校对中
- location3.0+
访问设备位置（getLocation）。ENAccessing 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