mraid explained.

Last updated October 16, 2026 · By the Bolt Playables team, 7,000+ playables built

What MRAID does

An HTML5 ad inside an app runs in a web view, cut off from the app around it. MRAID is the agreed set of JavaScript calls that bridges the two, so one ad can work in any SDK that supports the standard. For a playable ad it covers:

• Readiness: when the SDK has finished setting up and the ad can start.
• Visibility: whether the ad is actually on screen, so it doesn't run (or play sound) while hidden.
• Click-through: mraid.open() opens the store or a URL the way the SDK expects, and lets the network count the click.
• Size and orientation: the screen and ad size, and orientation preferences.

MRAID also defines calls for banners that expand or resize, which playables don't usually need.

What is mraid.js?

mraid.js is the script that creates the mraid object. The SDK supplies it, not you. The MRAID standard has the ad include <script src="mraid.js"></script> and the SDK answers that request with its own implementation. Some networks inject MRAID without the tag (Unity's docs don't ask for it). Never bundle your own copy, and never include the tag in a build for a network that doesn't use MRAID: several reject the file for it. Each network's page in our playable ad specs says what it expects.

The MRAID calls a playable ad uses

A safe MRAID start for playable ads

Wait for MRAID, start only when the ad is on screen, and open the store only from a tap:

function start() { /* start the game */ }
function pause() { /* pause the game and mute it */ }

function onViewable(viewable) {
  if (viewable) start(); else pause();
}

function onReady() {
  mraid.addEventListener("viewableChange", onViewable);
  if (mraid.isViewable()) start();
}

if (mraid.getState() === "loading") {
  mraid.addEventListener("ready", onReady);
} else {
  onReady();
}

installButton.addEventListener("click", function () {
  mraid.open(STORE_URL);
});

This is the pattern Unity's best-practices guide uses, and it works on any MRAID network. Set STORE_URL to your App Store or Google Play link, or follow the network's own rule (Liftoff calls mraid.open() with no URL).

MRAID 1.0 vs 2.0 vs 3.0

A playable that sticks to the calls in the table above works on 2.0 and 3.0 SDKs. Check mraid.getVersion() before using anything 3.0-only.

Which ad networks use MRAID

How to test an MRAID ad

1. On your desktop, with a small stand-in for the mraid object so the ad runs in a normal browser:

// Desktop testing only: a stand-in for the mraid object the SDK injects.
// Never ship this in a network build.
if (typeof window.mraid === "undefined") {
  window.mraid = {
    getState: function () { return "default"; },
    getVersion: function () { return "3.0"; },
    isViewable: function () { return true; },
    addEventListener: function () {},
    removeEventListener: function () {},
    open: function (url) { console.log("mraid.open", url); },
    close: function () { console.log("mraid.close"); }
  };
}

2. In the network's own test app, which runs the ad in the real SDK: AppLovin Playable Preview, or the Ad Testing app for Unity Ads.
3. On real phones, checking that the ad waits until it's on screen, pauses when hidden, and that the install button opens the right store page.

Common MRAID mistakes

• Calling MRAID before ready, which fails on SDKs that load it late.
• Starting before the ad is viewable, so the game runs, and plays sound, while hidden.
• Using window.open or a link instead of mraid.open(), so the click isn't counted or the store doesn't open.
• Shipping the desktop stub or your own mraid.js in a network build.
• Leaving mraid.js in a build for Meta, Google, TikTok or another non-MRAID network, the most common reason a playable built for one network fails on another.

For a playable ad's full requirements beyond MRAID, see how to make a playable ad.

Common questions