MRAID for playable ads

What MRAID is

MRAID stands for Mobile Rich Media Ad Interface Definitions. It’s a specification from the IAB (now IAB Tech Lab) that has given in-app ads, in their words, a common way to build rich ad experiences “since 2011”. It started with expandable banners and grew to cover resizing, orientation and full-screen interstitials, which is where playables run. The current version is MRAID 3.0, which is backward compatible with 2.0 containers.

In practice it’s a JavaScript object, window.mraid, that the app’s ad SDK injects into the web view showing your ad. Your HTML asks for it with one tag, as early as possible in the file:

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

There is no mraid.js file to ship. The SDK answers that request with its own implementation. In a desktop browser the tag loads nothing and window.mraid stays undefined, which is why every call needs a guard.

The parts a playable uses

Most of MRAID is about banners that expand and resize. A full-screen playable needs very little of it:

Unity’s docs show the ready check almost word for word: include the tag before any MRAID call, listen for ready, and use getState() in case it already fired. On deprecation, Google’s SDK docs recommend “a listener for the new exposureChange event rather than the deprecated viewableChange event” and add that the deprecated methods “continue to be supported to maintain backward compatibility”.

Which networks use it

This is what our export does for each network, read from its code (last checked 13 October 2026). Some networks reject a file that includes mraid.js, so it’s added only where it belongs.

AppLovin’s own guidelines are explicit: “HTML ads must support MRAID v2.0”, “Use mraid.open() for click-through actions”, and wait for the ready event “before calling any MRAID APIs”. ironSource’s export keeps mraid.js but opens the store through its own dapi.openStoreUrl() first. Meta’s playable docs ask for FbPlayableAd.onCTAClick() instead.

The start gate

A playable that starts the moment its file loads can play its first seconds to nobody, because the SDK can load the ad before it’s on screen. The fix is a gate that holds the game until MRAID is ready and the ad is on screen, and starts at once when there is no MRAID:

function whenAdReady(start) {
  var m = window.mraid;
  if (!m) return start();                 // plain browser, or a non-MRAID network
  function onReady() {
    if (m.isViewable()) return start();
    m.addEventListener("viewableChange", function v(visible) {
      if (!visible) return;
      m.removeEventListener("viewableChange", v);
      start();
    });
  }
  if (m.getState() === "loading") m.addEventListener("ready", onReady);
  else onReady();
}

whenAdReady(startGame);

The store button then goes through MRAID when it’s there:

function openStore() {            // only ever called from a tap
  if (window.mraid && mraid.open) mraid.open(STORE_URL);
  else window.open(STORE_URL, "_blank");
}

This uses isViewable() and viewableChange because MRAID 2.0 containers don’t have exposureChange, and the 3.0 SDKs above still support the older pair.

Common mistakes

• Calling mraid before it’s ready. Unity lists “Cannot read property ‘getVersion’ of undefined” as the sign that the interface isn’t there yet, or that the script tag is missing.
• Starting the timer or music on load. AppLovin: “Each ad’s timer must start only after the first user interaction”, and audio stays muted until then.
• Opening the store on a timer or the first tap. Only a tap on the store button or the end card should call mraid.open().
• Using window.open on an MRAID network. AppLovin warns that without mraid.open() “click-through fails”.
• Shipping mraid.js where it isn’t wanted. Meta, Moloco and TikTok exports leave it out.
• Leaving listeners attached. Remove the viewableChange listener once the game has started.

What our export does

You don’t write any of this in Playbaker. The game calls one start function and one openStore(); on export, the AppLovin, Unity Ads and ironSource files get the mraid.js tag and the start gate above, and openStore() is bound to that network’s call. On the other networks the gate starts the game when the page has loaded. QA checks that the store only opens from a tap and that no sound plays before one. More in playable ad best practices.

Questions

Sources, checked 16 October 2026: IAB Tech Lab, MRAID; Unity, Playable and interactive ads; Google, Mobile Rich Media Ads; AppLovin, Best practices & guidelines; Meta, Playable Ads for Mobile Apps.