What Is MRAID? The Playable Ad API Explained

MRAID is the standard contract between an HTML5 ad and the mobile SDK that displays it. Here is what it does, which calls matter for playables, and where it differs from clickTag and Exit API.

By the PlayableRun team··7 min read

Key takeaways - MRAID (Mobile Rich Media Ad Interface Definitions) is a standard API that lets an HTML5 ad communicate with the mobile app SDK that displays it. - Its most important job for playables is giving the ad a safe way to open the store page, close the ad, and react to visibility changes. - The SDK provides the MRAID object. Your ad checks for it, waits until it is ready, and only then starts. - MRAID is not the same as clickTag or Exit API. Those serve web display and Google Ads; MRAID serves in-app networks. - Networks often layer their own requirements on top of MRAID, so always read the current spec of the network you are building for.

What is MRAID?

MRAID stands for Mobile Rich Media Ad Interface Definitions. It is a specification maintained by the IAB Tech Lab. You can read the official page at IAB Tech Lab's MRAID standard.

The idea is simple. A mobile ad is usually HTML, CSS and JavaScript running inside a webview. That webview lives inside someone else's app, and the ad needs to ask that app for things. Can I open this URL? Can I close myself? Is the ad actually on screen right now?

Without a standard, every SDK would invent its own answers. Every creative would need custom code per SDK. MRAID is the shared vocabulary that avoids this. The SDK exposes a JavaScript object called mraid, and the ad uses it.

Think of it as a contract with two sides:

  • The container (SDK) promises to provide the mraid object, report state, and carry out requests like opening a link.
  • The creative (your ad) promises to use those calls instead of doing risky things directly, such as navigating the webview away from the ad.

Why playables need it

A playable ad is a tiny interactive app delivered as an HTML5 file. The player taps, the mechanic responds, and at some point the ad has to hand the player to your App Store or Google Play listing.

That last step is where a plain webview gets in the way. A normal link inside an ad webview might load the store's web page inside the ad frame, or do nothing at all. The SDK needs to be in control, because it tracks the click, attributes the install, and decides how to launch the store.

So the playable calls mraid.open(url) and the SDK handles the rest. The ad never needs to know whether it is running on iOS or Android, or which app is showing it.

The same logic applies to other moments:

  • Closing. An interstitial may need to dismiss itself after the player finishes.
  • Visibility. The ad should not start its timer, audio or animation loop while it is off screen.
  • Environment. The ad may want to know whether it is an inline or interstitial placement.

If you want the broader picture of what a playable file actually contains, What Is an HTML5 Ad? What's Inside the ZIP covers the packaging side.

The calls you will actually use

MRAID is a large spec, and most of it is aimed at rich media banners rather than playables. For a playable, a small set matters.

  • mraid.getState() returns where the ad is in its lifecycle. Values include loading, default, expanded, resized and hidden.
  • mraid.addEventListener(event, handler) subscribes to events such as ready, stateChange and viewableChange.
  • mraid.isViewable() tells you whether the ad is currently visible to the user.
  • mraid.open(url) asks the SDK to open a URL, which is your store link in a playable.
  • mraid.close() asks the SDK to close the ad.
  • mraid.getVersion() and mraid.supports(feature) let you check what the container can do before you rely on it.
  • mraid.getPlacementType() returns whether the placement is inline or interstitial.

Older versions of the spec also included calls for expanding, resizing, storing pictures and creating calendar events. Those matter for rich media banners. Playables rarely need them, and newer versions changed or dropped some of them, so check the spec rather than assuming.

The startup pattern

The most common MRAID bug in playables is starting too early. The mraid object may exist, but the container may not be ready. The standard pattern is to check the state and wait if needed.

function start() {
  // begin the playable: load assets, show the first screen
}

if (typeof mraid !== "undefined") {
if (mraid.getState() === "loading") {
mraid.addEventListener("ready", start);
} else {
start();
}
} else {
start(); // local preview, no SDK present
}
```

Then, if the ad has audio or a running animation loop, tie it to visibility:

mraid.addEventListener("viewableChange", function (viewable) {
  if (viewable) resume(); else pause();
});

And the store handoff becomes a single call:

function goToStore() {
  mraid.open("https://apps.apple.com/app/id000000000");
}

The fallback branch matters. You will preview the file in a desktop browser many times, and there is no mraid object there. A guard keeps the ad testable.

Who provides mraid.js

This trips up a lot of first-time builders. In the standard model, you do not ship the MRAID implementation. The SDK injects it into the webview when the ad loads. Your code just calls mraid.

If you bundle your own stub of mraid.js, you can shadow the real one and break click handling. Some networks explicitly tell you whether to include a script tag for it and some tell you not to. Follow the network's current instructions. If a network does not document it clearly, ask their support before you submit.

Since the SDK hosts the ad in a native webview, it also helps to know what that environment is. On Android it is the system WebView. On iOS it is WKWebView. Both are modern browsers, but they have their own autoplay, audio and storage rules, which is why testing inside a real SDK matters.

MRAID versions

The spec has gone through several versions. The ones you will meet most often are MRAID 1.0, 2.0 and 3.0.

  • 1.0 covered the basics: state, expand, close, open, and viewability.
  • 2.0 added richer features like resizing and device-facing helpers.
  • 3.0 modernised the model. It added better viewability and exposure reporting, audio volume events, and a clearer way for the container to declare what it supports.

In practice, you cannot assume the version. Use mraid.getVersion() and mraid.supports() when you depend on anything beyond the basics. For a playable that only needs open, close and viewableChange, you are on safe ground in nearly every container.

MRAID vs clickTag and Exit API

These get confused constantly because they all answer the same question: how does a click leave the ad?

  • clickTag is a convention for web display ads. The ad server passes a URL into the creative, and the creative uses it. See What Is clickTag?.
  • Exit API is Google's mechanism for HTML5 ads in Google Ads. The ad calls a function from Google's script so the click can be tracked and routed. See What Is Exit API in Google Ads?.
  • MRAID is the in-app SDK contract. The ad calls mraid.open() and the SDK launches the destination.

They are not interchangeable. A file built for one will usually not click through correctly in another. If you are weighing Google's HTML5 route against app campaigns, HTML5 Display Ads vs App Campaigns explains why the code differs.

Where MRAID is not enough

Even a perfect MRAID implementation may not pass a network's review. Reasons you may see:

  • Extra required calls. Some networks ask for their own function to signal gameplay start, game end or install intent, in addition to MRAID.
  • Packaging rules. Some want a single inline HTML file, others a ZIP. See Single File HTML Playable for why inline is common.
  • Size and behaviour limits. These change over time. Check each network's current spec rather than trusting a number from an old forum post.
  • Preview tools. Several networks provide a tester or preview app. Use it before uploading.

A practical checklist

  1. Wait for the container to be ready before starting.
  2. Route every store click through mraid.open().
  3. Pause audio and loops when the ad is not viewable.
  4. Keep a safe fallback so the file still runs in a desktop browser.
  5. Do not bundle your own mraid.js unless the network says to.
  6. Test on a real iOS and a real Android device through the network's own tester.
  7. Re-read the network spec each time you build for a new one.

If the mechanic itself is where you are stuck, Playable Ad Tutorial Design is a better next read than more API detail.

Where PlayableRun fits

Handling MRAID by hand is not hard, but it is repetitive. Doing it per network is where mistakes creep in. PlayableRun builds a playable from your store listing and exports a Google Ads-ready ZIP. For in-app networks, still confirm each network's own requirements before you upload.

If you want to see what a finished playable looks like, browse the demos. If you would rather try it on your own listing, you can create a free account.

Frequently asked questions

›What does MRAID stand for?

MRAID stands for Mobile Rich Media Ad Interface Definitions. It is a standard from the IAB Tech Lab that defines how an HTML/JavaScript ad talks to the mobile app SDK showing it.

›Is MRAID a file format?

No. It is an API contract. Your ad is still HTML, CSS and JavaScript. MRAID defines the functions and events the SDK exposes to that code, such as opening a store page or closing the ad.

›Do I need to include mraid.js in my ad?

Usually not. In the standard model the SDK supplies the MRAID object to the ad when it loads. Bundling your own copy can cause conflicts, so follow each network's spec for what to include.

›Does Google Ads use MRAID for HTML5 ads?

Google Ads HTML5 display ads use their own exit mechanism rather than MRAID. See the Exit API article for how that works. MRAID matters mainly for in-app networks that render ads in an SDK webview.

›Is MRAID enough to get a playable accepted by every network?

Not always. Many networks add their own requirements on top, such as specific install or tracking calls, packaging rules and size limits. Check each network's current spec before you submit.

Sources

Turn your store listing into a playable

Paste an App Store or Google Play link and get an HTML5 playable you can test in minutes. The first one is free.

Keep reading