MRAID

What is MRAID ?

MRAID, or “Mobile Rich Media Ad Interface Definitions,” is the common API for rich media ads that will run in mobile apps. This is a standardized set of commands, designed to work with HTML5 and JavaScript, that developers creating rich media ads use to communicate what those ads do (expand, resize, get access to device functionalities such as the accelerometer, etc.) with the apps into which they are being displayed.

More info available in the IAB MRAID page.

MRAID support

Smart Display SDK supports MRAID 2.0

Here is the list of supported features from the IAB MRAID common API.

Good practices

Ways of counting viewable impressions

For viewable impressions counting, the use of MRAID 2.0 method isViewable is recommended. It is important to rely on isViewable or listen to viewableChange events to make sure that creative knows when to initiate counting viewable impressions.

Ways of counting impressions

Starting from SDK version 7.0, the interstitial is loaded then shown asynchronously.

If a third party impression counting pixel is fired by the creative itself, it's important that the creative rely on the MRAID ready event to count properly and avoid discrepencies.

Ways of starting HTML5 animation / video

When the HTML5 animation or video tag are loaded into the containing webview, it is important to rely on isViewable or listen to viewableChange event to make sure that creative knows when to start the ad experience (animation, video autoplay)

Please note: Smart Display SDK handles banners in scrollviews for the isViewable value and viewableChange event.

Custom MRAID APIs

Smart Display SDK proposes custom methods and events to enhance ad experience and integration inside your app.

Please note that features described in this section are offered by the implementation of MRAID by the Smart Display SDK but are not part of the IAB MRAID specification.

MRAID messaging between the creative and the app

Smart Display SDK allows you to send text messages to the HTML5 creative and to retrieve messages sent from it. This can be useful to start/stop animated content in your ad depending on a particular event in your application.

Send a message to the creative

• When the creative is ready, the native application can send a String object as message using sendMessageToWebView method. Using an empty or a null/nil string will not trigger the event on the creative.

  
  // to inform the creative that it can start the animation
  bannerView.sendMessageToWebView("startAnimation");
  		    

  
  // to inform the creative that it can start the animation
  [self.bannerView sendMessageToWebView:@"startAnimation"];
  		      

• The message can be retrieved from the creative by registering to the sasReceiveMessage MRAID event.

  
  mraid.addEventListener("sasReceiveMessage", function(message) {
      console.log("Received message from native app: " + message);
  });
  			

Please note: sending and receiving messages are two separates API: one can be supported by the native app and not the other. Be sure that you check the availability of the API you are actually using.

Receive a message from the creative

• The creative can send a message to the app. To receive this message as a String object, you simply need to implement on iOS the SASBannerViewDelegate bannerView:didReceiveMessage: delegate method and on Android the SASAdView.MessageHandler interface handleMessage() method.

  
  bannerView.setMessageHandler(new SASAdView.MessageHandler() {
  	@Override
  	public void handleMessage(String message) {
  		// code to process the message here
  	}
  });
  		    

  
  			- (void)bannerView:(SASBannerView *)bannerView didReceiveMessage:(NSString *)message {
  			    // code to process the message here
  			}
  		    

• The message can be sent from the creative using mraid.sasSendMessage() method:

  
  mraid.sasSendMessage("message");
  			

Please note that sending and receiving messages are two separates API: one can be supported by the native app and not the other. Be sure that you check the availability of the API you are actually using.