The Google Mobile Ads SDK now has beta support for MRAID v3, built on existing support for MRAID v2, enabling advertisers to serve MRAID v3 creatives to Ad Manager publishers. This guide clarifies the MRAID implementation details that were unclear and open to interpretation in the MRAID v3 spec. Its intended audience is MRAID v3 creative authors.
Prerequisites
Publishers must be running:
- Google Mobile Ads SDK for iOS 7.30.0 or higher for MRAID v3
- Google Mobile Ads SDK for iOS 7.4.0 or higher for MRAID v2
Helpful primers
If you are not familiar with MRAID, you can learn more at the IAB MRAID page. You can also download the MRAID v3 Definitions document, which gives details about all the parameters discussed below, as well as the IAB blog post on MRAID v3.
MRAID v3 (beta) implementation details
Viewability - exposureChange event
This event is supported and we recommend using a listener for the new
exposureChange event rather than the deprecated viewableChange event.
The method mraid.isViewable() is also deprecated. These deprecated methods
continue to be supported to maintain backward compatibility however.
The exposureChange event definition is dispatched whenever the ad view
changes. The SDK has a polling mechanism to avoid generating too many events.
The initial state is asynchronously sent after the ad registers a listener.
The callback includes the exposed_percentage param which is a floating-point
number between 0.0 and 100.0.
Refer to the MRAID v3 specification for sample usage.
MRAID detection and initialization and MRAID_ENV attributes
The SDK conforms to the initialization protocol as defined in the MRAID v3 spec.
In the MRAID_ENV object, the SDK does not send IDFA, limitAdTracking,
App ID, or COPPA (which are optional). It provides all required variables
in the MRAID_ENV object, including MRAID version, SDK name, and SDK version.
Audibility measurement
A new event (audioVolumeChange) is introduced to identify whether the audio
can be heard and when the volume changes.
The audioVolumeChange event has a single parameter: volume_percentage.
The value is the percentage of maximum audio playback volume. It is a
floating-point number between 0.0 and 100.0 (0.0 when playback
is not allowed) or null if volume can't be determined.
Refer to the MRAID v3 specification for sample usage.
mraid.getLocation()
Because mraid.getLocation() is not supported, it always returns -1.
mraid.unload()
This method can be called at any time and the SDK reacts by dismissing the ad, deallocating the resources, and then either removing the webview or replacing it with another document or a new ad.
When the creative calls unload(), the native layer responds as follows
for the different creative types:
| Type | unload() Behavior |
|---|---|
| Banner | Make a new ad request with the same request parameters as the current ad. |
| Interstitial | Close the interstitial. |
VPAID (Video Player Ad Interface Definition)
The Google Mobile Ads SDK does not support VPAID. mraid.supports('vpaid')
returns false.
mraid.useCustomClose()
mraid.useCustomClose() might not be supported, depending on the format and
creative type.
MRAID v2 implementation details
mraid.getVersion()
mraid.getVersion() does not return 2.0 until the creative has loaded. Do not
check the MRAID version while mraid.getState() returns loading.
mraid.resize()
When mraid.resize() is called, the original banner is replaced with the
screenshot image of the banner. This is noticeable if the resized ad
doesn't cover the original ad space.
Resized ads also do not follow the original banner frame. If a banner is placed in a scrolling view, the resized ad does not scroll with the banner.
mraid.setResizeProperties()
All calls to mraid.setResizeProperties() should contain a complete list of
required properties. If the resize properties are invalid, they will be set back
to their defaults, and all subsequent calls to mraid.resize() will fail until
mraid.setResizeProperties() is called again with valid parameters.
mraid.getMaxSize()
mraid.getMaxSize() should only be used to determine the maximum size for resized
ads. To determine the size of an expandable ad, use mraid.getScreenSize().
mraid.setOrientationProperties()
When calling mraid.setOrientationProperties() with the allowOrientationChange
property set to true, setting the forceOrientation property won't do anything.
Creatives that want to force orientation should set allowOrientationChange to
false.
mraid.isViewable()
If a view covers an otherwise visible ad, mraid.isViewable() will still return
true. App content should not cover visible ads.
mraid.getCurrentPosition()
While a two-piece expandable ad is in the expanded state, a call to
mraid.getCurrentPosition() on the first piece will return the size of the
screen.
mraid.supports()
Starting in SDK version 7.11.0, mraid.supports("storePicture") and
mraid.supports("calendar") always return false. Per the MRAID v2 spec,
creatives should be able handle the case where these methods are unavailable.
mraid.storePicture()
The app automatically requests permission to save an image
when an MRAID creative calls mraid.storePicture().