MRAID is an industry standard API for rich media ads running in mobile applications (http://www.iab.net/mraid). It provides banner ads with a standard way to expand/collapse banners and handle other situations that are not possible in a mobile application environment.

Inheritance

Constructor

mraid()

Instance Methods

Defined in mraid
addEventListener(event, listener, opt_capture, opt_handlerScope)
Adds an observer for events dispatched by the ad environment. The supported events are:
  • mraid.EventType.READY (ready)
  • mraid.EventType.ERROR (error)
  • mraid.EventType.STATE_CHANGE (stateChange)
  • mraid.EventType.VIEWABLE_CHANGE (viewableChange)
Refer to mraid.EventType for details on EventTypes.
Arguments:
event :
mraid.EventType | string
Name of event to listen for.
listener :
Function
Function to execute.
opt_capture :
(boolean | undefined)
Determines whether the listener is fired during the capture or bubble phase of the event.
opt_handlerScope :
(Object | null | undefined)
Object in whose scope to call the listener.
close()
Downgrades the state of the ad. It will also fire the stateChange event.

  • For ads in an expanded state, close causes the StateType to transition to the default state.
    • This method may be used by ad designers as an addition to the SDK-enforced close ability.

expand(url)
Causes the ad experience to go full-screen to the size of the device, dispatching a stateChange event.
  • If invoked with a url in the first parameter, it will load that URL in the full-screen area, hiding the original banner.
  • If invoked without a url parameter, it will place the current creative into the expanded full-screen area. The original creative is not reloaded and no additional impressions are recorded.
Arguments:
url :
(null | string)
Optional URL to be displayed in a new overlay view. If null, the body of the current ad will be used in the current view.
getExpandProperties() ⇒
Object
Returns the expand properties. Refer to mraid.ExpandProperty.
Returns: 
Object
  A JSON Object containing expand properties.
getPlacementType() ⇒
mraid.PlacementType | string
Returns the mraid.PlacementType of an ad. The supported placement types are:
  • mraid.PlacementType.INLINE (inline) (also called banner)
  • mraid.PlacementType.INTERSTITIAL (interstitial)
Refer to mraid.PlacementType.
Returns: 
mraid.PlacementType | string
  The placement type.
getState() ⇒
mraid.StateType | string
Returns the mraid.StateType of an ad. The supported states are:
  • mraid.StateType.LOADING (loading)
  • mraid.StateType.READY (ready)
  • mraid.StateType.EXPANDED (expanded)
  • mraid.StateType.HIDDEN (hidden)
Refer to mraid.StateType.
Returns: 
mraid.StateType | string
  The state.
getVersion() ⇒
string
Returns the version of MRAID specification in use. Ad developers can use this method to confirm a basic feature set at runtime.
Returns: 
string
  The current version is "1.0".
isViewable() ⇒
boolean
Returns whether the ad container is currently on or off the screen. The viewableChange event fires when the ad moves from on-screen to off-screen and vice versa.

This is helpful when the ad is of type mraid.PlacementType.INTERSTITIAL. An interstitial loads off the screen, so wait for it to be on-screen before starting animations, timers, etc.

Returns: 
boolean
  Whether the ad container is currently on or off screen.
open(url)
Opens an external URL in a browser. On iOS the browser window remains in the application. On Android the native browser is invoked.
Arguments:
url :
string
The URL of the web page.
removeEventListener(event, listener, opt_capture, opt_handlerScope)
Unsubscribes a specific handler method from a specific event. Event listeners should always be removed when they are no longer useful to avoid errors. If no listener function is provided, then all functions listening to the event will be removed.
Arguments:
event :
mraid.EventType | string
Name of event to listen for.
listener :
Function
Function to execute.
opt_capture :
(boolean | undefined)
Determines whether the listener is fired during the capture or bubble phase of the event.
opt_handlerScope :
(Object | null | undefined)
Object in whose scope to call the listener.
setExpandProperties(properties)
Sets the expand properties.

The expand properties object is intended to provide additional features to ad designers. In MRAID v.1.0, expand properties that can be set by the ad designer are limited to the width and height of the ad creative in pixels, and whether the creative is supplying its own close indicator.

Refer to mraid.ExpandProperty.

Arguments:
properties :
Object
JSON object containing expand properties.
useCustomClose(useCustomClose)
Sets the useCustomClose of expand properties.

This method serves as a convenience method to mraid.ExpandProperty.useCustomClose. Setting the property or calling this method both have the same effect and can be used interchangeably. If an ad sets useCustomClose via both expand properties AND this method, whichever is invoked later will override the earlier setting. They signal the SDK to stop using the default close indicator.

  • For expanded ads, the designer does not need to call this method and would normally set the useCustomClose property in setExpandProperties().
  • For a stand-alone interstitial where there is no call to expand(), but there is still a close() requirement, the ad designer should call this method as early as possible.
    • Ad designers should be clear that an MRAID-compliant SDK is required to show the default close indicator until the useCustomClose is called and/or the property is set.

Arguments:
useCustomClose :
boolean
The boolean that sets whether the ad creative supplies its own close button.

Enumerations

mraid.EventType :
Events dispatched when the ad's state changes. To listen for these events use the addEventListener method.
Constants:
STATE_CHANGE
Dispatched when the state was changed.
VIEWABLE_CHANGE
Dispatched when the viewable was changed.
ERROR
Dispatched when an error has occurred.
READY
Dispatched when initialization is complete.
mraid.ExpandProperty :
The expand properties is intended to provide additional features to ad designers. They are used in setExpandProperties
Constants:
WIDTH
Width : integer

The width of creative in pixels, default is full screen width.

This is not supported by the AdMob SDK.

IS_MODAL
isModal : boolean

  • true, the SDK is providing a modal container for the expanded ad.
  • false, the SDK is not providing a modal container for the expanded ad.
This property is read-only and cannot be set by the ad designer.

HEIGHT
Height : integer

The height of creative in pixels, default is full screen height. Note that when getting the expand properties before setting them, the values for width and height will reflect the actual values of the screen. This will allow ad designers who want to use application or device values to adjust as necessary.

This is not supported by the AdMob SDK.

USE_CUSTOM_CLOSE
UseCustomClose : boolean

  • true, SDK will stop showing default close graphic and rely on ad creative?s custom close indicator.
  • false (default), SDK will display the default close graphic.
This property has exactly the same function as the useCustomClose method and is provided as a convenience for creators of expandable ads.

mraid.PlacementType :
Placement Type.

For efficiency, ad designers sometimes flight a single piece of creative in both banner and interstitial placements. So that the creative can be aware of its placement, and therefore potentially behave differently, each ad container has a placement type determining whether the ad is being displayed inline with content (i.e. a banner) or as an interstitial overlaid content (e.g. during a content transition). The SDK returns the value of the placement to creative so that creative can behave differently as necessary. The SDK does not determine whether a banner is an expandable (the creative does) and thus does not return a separate type for expandable.

Constants:
INTERSTITIAL
Interstitial placement type. The ad is being displayed as an interstitial overlaid content (e.g. during a content transition).
INLINE
Inline placement type. The ad is being displayed inline with content (i.e. a banner).
mraid.StateType :
State of the Ad. To access the state of an ad use the getState method.
Constants:
HIDDEN
In the hidden state, the ad container no longer display the ad.
DEFAULT
The default state shows the ad in the initial position and size of the ad container as placed by the application and SDK.
LOADING
In the loading state, the SDK is not yet ready for interactions with the Controller
EXPANDED
In expanded state, the ad container has expanded to cover the application content at the top of the view hierarchy.

Package

Package Reference