Playable and interactive ads#

Playable ads are the second-most popular type of ad shown on Unity Exchange. Because all Unity inventory is mobile in-app projects, the majority of it supports playable ads.

MRAID#

Mobile Rich Media Ad Interface Definitions (MRAID) is the common API for mobile rich media ads that run in mobile apps. MRAID provides a way for ad developers to design interactive ads that work in MRAID-compliant systems, using common code. MRAID controls how ads interact in the apps where they appear.

Identification and initialization#

To ensure your ads are compatible with the Unity MRAID interface:

• Identify them as being MRAID compliant by including an MRAID script tag (<script src=”mraid.js”></script>) as early as possible in the ad's code, before referencing any MRAID functions.

• Use the addEventListener function to detect when the MRAID state changes from "loading" to "ready".

• Use the getState method to verify a "ready" state before showing the ad. This prevents timing issues, such as the ready event firing before the ad has been registered.

function showMyAd() {
   // Ad content
}

if (mraid.getState() === ‘loading’) {
   mraid.addEventListener(‘ready’, showMyAd);
} else {
   showMyAd();
}

Access the MRAID_ENV object to verify any additional information you need before initialization. This variable is attached to the window object and contains the following attributes:

For more information on how to identify and initialize MRAID functionality, refer to the IAB documentation.

Events#

Ads must register event listeners to receive any of the following events. For more information, refer to the addEventListener and removeEventListener methods.

error#

This event triggers whenever the host cannot execute a function called by the ad.

error(message: string, action: string): void

ready#

This event triggers when initialization completes.

ready()

sizeChange#

This event triggers whenever the ad container dimensions change (for example, as a response to device orientation changes).

sizeChange(width: number, height: number)

stateChange#

This event triggers whenever the state of the ad container changes.

stateChange(state: string)

exposureChange#

This event triggers whenever there is a change in the exposure of the ad. Examples include when:

• The ad displays.
• The ad closes.
• The application has a foreground or background.
• The ad container’s exposure is altered (for example, the user opens the privacy settings).

exposureChange(exposedPercentage: number, visibleRectangle: Rectangle | null, occlusionRectangles: Rectangle[] | null)

audioVolumeChange#

This event triggers whenever the device’s volume changes.

audioVolumeChange(volumePercentage: number): void

viewableChange (deprecated)#

Important: This event has been deprecated in MRAID 3.0. However, Unity still supports it to maintain backward compatibility.

This event triggers whenever there is a change in the viewability of the ad. Examples include when:

• The ad displays.
• The ad closes.
• The application has a foreground or background.

viewableChange(viewable: boolean): void

Supported methods#

Unity supports the following MRAID methods:

• addEventListener
• close
• getCurrentAppOrientation
• getCurrentPosition
• getDefaultPosition
• getMaxSize
• getPlacementType
• getScreenSize
• getState
• getVersion
• isViewable
• open
• removeEventListener
• supports
• unload

addEventListener#

Use this method to subscribe a specific handler function to a specific event. Multiple listeners can be subscribed to a specific event and a single listener can handle multiple events.

addEventListener(event: string, listener: function): void

close#

Use this method to downgrade an ad container’s state. Because Unity does not currently support both expand and resize methods, this method can only change an ad from the default state to a hidden state.

close():void

getCurrentAppOrientation#

Use this method to query the device for the current orientation of the app.

getCurrentAppOrientation(): { orientation: string, locked: boolean }

Return values#

getCurrentPosition#

Use this method to return the current position and size of the ad view, measured in density-independent pixels.

getCurrentPosition():JavaScriptObject

Return values

{x: number, y: number, width: number, height: number}

getDefaultPosition#

Use this method to return the position and size of the default ad view, measured in density-independent pixels, regardless of what state the calling view is in.

getDefaultPosition():JavaScriptObject

Return values

{x: number, y: number, width: number, height: number}

getMaxSize#

Because Unity does not support the expand and resize methods, this method always returns the maximum size (in density-independent pixel width and height) of the ad's container. The return values for full-screen interstitial ads will always be the full screen dimensions.

getMaxSize():JavaScriptObject

Return values

{width: number, height: number}

getPlacementType#

This method returns the type of placement, which might affect the creative's behavior.

getPlacementType():string

Return values#

getScreenSize#

This method returns the actual pixel width and height, based on the current orientation in density-independent pixels, of the device on which the ad is running.

getScreenSize():JavaScriptObject

Return values

{width: number, height: number}

getState#

This method returns the current state of the ad container. Because Unity does not support the expand and resize methods, the ad state will never return “expanded” or “resized” values.

getState(): string

Return values#

getVersion#

This method returns the version of the MRAID interface that Unity supports, allowing the bidder to confirm the basic features before display.

getVersion():string

Return values#

isViewable (deprecated)#

Important: This event has been deprecated. However, Unity still supports it to maintain backward compatibility.

This method returns whether the ad container is currently on or off the screen.

isViewable():boolean

Return values

open#

This method displays an embedded browser window in the application that loads an external URL. On device platforms that do not allow an embedded browser, this method invokes the native browser with the external URL.

open(url:string):void

Parameters#

removeEventListener#

Use this method to unsubscribe a specific handler method for a specific event. You should always remove event listeners when they're no longer in use to avoid errors.

removeEventListner(event: string, listener: fuction: void)

Parameters#

supports#

This method returns whether the requesting device supports a specific feature.

supports(feature:string):boolean

Parameters#

Return values

unload#

This method informs the host that the ad should no longer be shown to the user. Use this method if the ad encounters errors or runtime exceptions that do not allow it to render correctly.

unload(): void

Unsupported methods#

Unity does not support the following methods:

• createCalendarEvent
• expand
• getExpandProperties
• getLocation
• getResizeProperties
• initVpaid
• playVideo
• resize
• setExpandProperties
• setResizeProperties
• storePicture
• useCustomClose

Troubleshooting#

If you get an Uncaught TypeError such as the following example, it might indicate that the MRAID interface is not available yet, or that the ad creative failed to include the <MRAID> script tag so the interface was never attached.

Example#

Uncaught TypeError: Cannot read property 'getVersion' of undefined.

This error would occur if you try to call the getVersion method without including the <MRAID> script tag. To correct this, add the script tag in earlier in the code, before referencing any MRAID functions.