MRAID

MRAID (Mobile Rich Media Ad Interface Definitions) is used to pass data back and forth between the SDK and an HTML banner. The SDK uses a special bridge to send events to the banner and process incoming commands. On the banner side, mraid.js must be included to give the HTML creative the methods it needs to communicate with the SDK bridge. OpenRTB signals support for this in the api array — for example, imp.banner.api = [3, 5, 7].

MRAID capabilities:

Expand: A 320x50 banner can expand to full screen when tapped.
Close: The creative renders its own close button and can send a command to dismiss the ad.
Store Picture: Prompts the user to save an image to their photo gallery.
Create Calendar Event: Adds an event to the phone's calendar, for example, the start of a sale.

Standards v2.0 and v3.0.

MRAID architecture in the SDK

MRAID is implemented in the SDK as a system of components that handle communication between HTML banners and the app's native code.

Android SDK

iOS SDK

SdkBannerHtmlAd: Main class for handling HTML banners.
SdkFullscreenHtmlAd: Class for full-screen HTML ads.
MraidCompatibilityDetector: MRAID compatibility detector.
HtmlWebViewAdapter: WebView adapter with MRAID support.

MACMraidWebView: Primary WebView component for MRAID.
MACMraidController: Controller for managing MRAID state.
MACMraidBridge: Bridge for communicating with JavaScript.
MACMraidScriptInjector: Injector for the mraid.js script.

Mraid.js integration

Any HTML banner supporting MRAID (MRAID-compliant) must contain the following string:

<script src="mraid.js"></script>

Since this tag doesn't need to sit at the very top or bottom of the HTML code and can include extra attributes inside the script tag, MRAID compatibility is checked using a regular expression:

// iOS
private let mraidInjectScriptRegExp = "(<script)(.*)(src=\"mraid\\.js\")(.*)(<\\/script>)"

// Android
private val MRAID_JS_REG_EXP_PATTERN = Pattern.compile("(<script)(.*)(src=\"mraid\\.js\")(.*)(<\\/script>)")

API methods for mraid.js

Here are the methods currently implemented in mraid.js (version 0.15):

Accepted requests

`getVersion()`	Returns the MRAID version (currently version 2.0).
`isViewable()`	Shows whether the banner is visible. The default value is `false`.
`getState()`	Returns one of the following states: `loading`, `default`, `expanded`, `resized`, or `hidden`. The default value is `loading`.
`addEventListener(event, listener)`	Adds an event listener for a specific event: `ready`, `error`, `stateChange`, `viewableChange`, `sizeChange`, `exposureChange`.
`removeEventListener(event, listener)`	Removes an event listener.
`fireChangeEvent(properties)`	Sets the `visibility`, `state`, `supports`, and `exposure` properties.
`setState(stateArg)`	Sets the state.
`setDefaultPosition(position)`	Sets the banner's default position (frame) inside the WebView.
`getDefaultPosition()`	Returns the banner position in WebView (undefined by default).
`setCurrentPosition(position)`	Sets the current position (frame) of the banner in WebView.
`getCurrentPosition()`	Returns the current banner position in WebView (undefined by default).
`notifyReadyEvent()`	Converts the banner to the `ready` state, similar to the `main()` function for the banner.
`notifyErrorEvent(message, action)`	Notifies the banner that an error occurred.
`nativeCallComplete()`	Notifies the banner that the SDK has processed the command and is ready for the next one.
`supports(feature)`	Returns a boolean flag that shows whether a feature in `supports` (`sms`, `tel`, `calendar`, `storePicture`, `inlineVideo`) is supported.

Commands called in the SDK

`useCustomClose(shouldUseCustomClose)`	Hides or shows the native close button based on whether `shouldUseCustomClose` is set to true or false. If this command isn't called, the close button renders by default. This command only works for interstitial banners.
`open(url)`	Opens the URL provided in the command. It's treated as a link click.
`close()`	Closes the banner if it's an interstitial ad. Otherwise, it does nothing.
`executeNativeCall(args)`	Calls a command in the SDK.

Additional MRAID commands

In addition to standard commands, the SDK supports extra commands for expanded functionality:

`advideocomplete`	Notifies the SDK that the video ad finished playing.
`adRendered`	Notifies the SDK that the ad fully rendered (used to optimize loading performance).
`impressionTrackingStart`	Starts tracking ad impressions.
`impressionTrackingSuccess`	Confirms that impression tracking succeeded.
`rewardedAdComplete`	Reports that the user finished watching the rewarded ad.

Events sent from the SDK to mraid.js

The SDK sends the following events to mraid.js:

`notifyReadyEvent()`	Notifies mraid.js that the SDK initialized the banner and is ready to show it. It triggers right after the banner loads into the WebView.
`fireChangeEvent(property)`	Edits a single property in mraid.js. Supported properties: `visibility`, `supports`, `state`.
`fireChangeEvent(properties)`	Edits multiple supported properties at once.
`nativeCallComplete()`	Notifies mraid.js that the SDK completed processing an MRAID command and is ready for the next one.

Was the article helpful?

Interstitial and rewarded ads

OM SDK