Playable and interactive ads

Deliver interactive playable ads through Unity Exchange.

Read time 6 minutes

Last updated 2 days ago

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:

Attribute	Type	Example	Description
`version`	string	`"3.0"`	The version of the implemented MRAID interface.
`sdk`	string	`"The Unity Ads SDK"`	The name of the SDK running the webview.
`sdkVersion`	string	`"4.0"`	The version of the SDK running the webview.
`appId`	string	`"com.unity3d.ads.example"`	The package name or application ID of the app running the ad.
`limitAdTracking`	boolean	`true`	`true` indicates that Limit Ad Tracking is active, and `false` indicates that it is not.
`coppa`	boolean	`true`	`true` indicates that the app is directed at children, and `false` indicates that it is not.

Note

Unity does not support the

ifa

attribute.

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

Parameter	Type	Description
`message`	string	A description of the error.
`action`	string	The name of the MRAID action called when the error triggered.

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)

Parameter	Type	Description
`width`	number	The width of the new view.
`height`	number	The height of the new view.

stateChange

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

stateChange(state: string)

Parameter	Type	Description
`state`	string	An indication of the ad container's state. This can be `"loading"` , `"default"` , or `"hidden"` .

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)

Parameter	Type	Description
`exposedPercentage`	number	The percentage of the ad that is visible on the screen (between `0.0` and `100.0` ).
`visibleRectangle`	`Rectangle`	The visible portion of the ad container, formatted as `{x, y, width, height}` . Returns `null` if nothing is visible.
`occlusionRectangles`	`Rectangle` array	An array of rectangles describing any sections of the `visibleRectangle` that are not visible, or `null` if the entire rectangle is visible. Each occlusion rectangle in the array is formatted as `{x, y, width, height}` .

audioVolumeChange

This event triggers whenever the device's volume changes.

audioVolumeChange(volumePercentage: number): void

Parameter	Type	Description
`volumePercentage`	number	The percentage of maximum volume set on the device (between `0.0` and `100.0` ).

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

Parameter	Type	Description
`viewable`	boolean	`true` indicates that the ad container is on-screen, and `false` indicates that it is not.

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

Parameter	Type	Description
`event`	string	The name of the event to listen to. For a complete list, refer to the section on events.
`listener`	object	The function to execute when the event triggers.

Note

Remove event listeners when they are no longer in use. For more information, refer to the documentation on the removeEventListener method.

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

Note

This method triggers the

stateChange

event.

getCurrentAppOrientation

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

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

Return values

Value	Description
`orientation`	A string describing the orientation of the app. This can be `"landscape"` or `"portrait"` .
`locked`	A boolean indicating whether the orientation is locked in its current position, where true indicates that the orientation is locked. Note The `forceOrientation` attribute in `setOrientationProperties` is not supported when the orientation is locked.

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}

Value	Description
`x`	The number of pixels offset from the left edge of the rectangle defined by `getMaxSize()` .
`y`	The number of pixels offset from the top of the rectangle defined by `getMaxSize()` .
`width`	The current width of the container in pixels.
`height`	The current height of the container in pixels.

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}

Value	Description
`x`	The number of pixels offset from the left edge of the rectangle defined by `getMaxSize()` .
`y`	The number of pixels offset from the top of the rectangle defined by `getMaxSize()` .
`width`	The current width of the container in pixels.
`height`	The current height of the container in pixels.

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}

Value	Description
`width`	The current width of the container in pixels.
`height`	The current height of the container in pixels.

getplacementtype

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

getplacementtype():string

Return values

Value	Description
`"inline"`	Indicates an inline ad placement.
`"interstitial"`	Indicates an interstitial ad placement.

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}

Value	Description
`width`	The maximum width of the screen size in pixels.
`height`	The maximum height of the screen size in pixels.

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"

"resized"

values.

getState(): string

Return values

Value	Description
`"default"`	Indicates that the ad container is in its default visible state.
`"hidden"`	Indicates that the ad container is hidden.
`"loading"`	Indicates that the ad container is loading.

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

Value	Description
`3.0`	Indicates that the MRAID interface is version 3.0.

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

Value	Description
`true`	The container is on screen and viewable.
`false`	The container is off screen and not viewable.

Note

This method triggers the

viewableChange

event.

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

Parameter	Type	Description
`url`	string	The URL of the external web page.

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

Parameter	Type	Description
`event`	string	The name of the event the listener is subscribed to, which can include: `"error"` `"ready"` `"sizeChange"` `"stateChange"` `"viewableChange"`
`listener`	function	The function to be removed.

supports

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

supports(feature:string):boolean

Parameters

Parameter	Type	Description
`event`	string	The name of the feature to query: `"calendar"` `"inlineVideo"` `"sms"` `"storePicture"` `"tel"`

Return values

Value	Description
`true`	The device supports the queried feature.
`false`	The device does not support the queried feature.

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.

Playable and interactive ads

MRAID

Identification and initialization

Attribute

Type

Example

Description

Events

error

Parameter

Type

Description

ready

sizeChange

Parameter

Type

Description

stateChange

Parameter

Type

Description

exposureChange

Parameter

Type

Description

audioVolumeChange

Parameter

Type

Description

viewableChange (deprecated)

Parameter

Type

Description

Supported methods

addEventListener

Parameter

Type

Description

close

getCurrentAppOrientation

Return values

Value

Description

getCurrentPosition

Return values

Value

Description

getDefaultPosition

Return values

Value

Description

getMaxSize

Return values

Value

Description

getplacementtype

Return values

Value

Description

getScreenSize

Return values

Value

Description

getState

Return values

Value

Description

getVersion

Return values

Value

Description

isViewable (deprecated)

Value

Description

open

Parameters

Parameter

Type

Description

removeEventListener