MRAID support in Cxense Advertising

What is MRAID?

MRAID is the common API for mobile rich media ads that will run in mobile apps.

General information on MRAID and it's current state can be found here: https://www.iab.com/guidelines/mobile-rich-media-ad-interface-definitions-mraid/

Specification itself (for current official version) can be found here: http://www.iab.com/wp-content/uploads/2015/08/IAB_MRAID_v2_FINAL.pdf

Here is the list of main MRAID 2.0 methods:

Which MRAID 2.0 methods does Cxense Advertising support?

Full support of MRAID 2.0 is in the product backlog. But at the moment CxAd provides a way to support isViewable method. For that you may make some changes in your application. All other methods can be supported per request.

How MRAID viewability will work on my CxAd network?

Firstly your application should be changed. Please find an instruction below.

After that you should create HTML5 creative (see HTML 5 Creatives) on CxAd with MRAID functions.

Next it should be decided how to display in-view impression in CxAd. At the moment there is no specific metrics but as workaround you may use conversions to count in-view impressions. Please check CxAd: Conversion Tracking to tune your sites for conversion tracking.

Developer guide 

MRAID support:

 Specification itself defines main actors, tools and / or resources that needed to be presented to work with MRAID. Basically you need few things to have support of MRAID ads: 

• mraid.js provider

• mraid-compatible ad creative

• mraid-compatible SDK from mobile platform side 

Let's discuss this in details: 

'mraid.js' is simple javascript file that must be added to ad creative's html body. The script contains list of functions along with their implementations that are implementation of functions described in MRAID specification text. 'mraid.js' does not provided by IAB. It is third-party vendors who are responsible for providing different implementations of 'mraid.js'. 

Compatible with MRAID specification ad creative is just a html creative that contains import of 'mraid.js' on the page and some javascript functions described in MRAID specification. Importing script file allows it functions usage in creative body. Creative need to implement some logic (also described in specification) to be able to be shown on the screen and to be able to interact with native mobile application.  

And finally you need to have compatible SDK in your mobile application that supports MRAID functions described in the specification. Some of the SDKs are provided with own implementation of 'mraid.js'. Some not.  

MRAID support in Ad SDK

Basically - Ad SDK does not support MRAID ads out-of-box. We (as Ad SDK creators) does not provide own implementation of 'mraid.js' that is needed to be presented to interact with native platform. And the SDK itself does not support any APIs related to MRAID specification. 

But Ad SDK public APIs provide extension points that can be used to implement support of MRAID ads. 

How to support MRAID ads with Ad SDK? 

Let's discuss each step in detail: 

Step 0. Preparations

Setup MRAID-compliant creative on Cxense Advertising. Pay attention that according to MRAID specification creative's body should contain following tag: 

<script src="mraid.js"></script>

 It said that such line indicate that ad container must inject the script by itself. As already was said - Ad SDK does not provide own implementation of "mraid.js", so, you need to use your own. Just add tag specified above with correct location of the script. 

Step 1. Showing MRAID-compliant ad 

Now when you have MRAID-compliant ad configured on Cxense Advertising servers in particular ad space, you can implement basic support of it's rendering. According to MRAID specification any MRAID-compliant ad must be initialized by it's container. Underlying web view instance that can be accessed through SDK's public APIs is ad's container. 

MRAID reference contains following information about ad's initialization: 

If MRAID State=”loading” then ad listens for “ready” event with mraid.addEventListener('ready') 

and 

SDK/Container finishes initializing MRAID library into the webview 

Here how you can implement these steps: 

@Override
public void onViewCreated(View view,
                          Bundle savedInstanceState) {
    // Imagine that your AdView was added to activity's xml file
    mAdSpace = (AdView) view.findViewById(R.id.cxenseView1);
    // Set your own WebClient's implementation that can initialize MRAID ad's state
    mAdSpace.getWebView().setWebViewClient(new WebViewClient() {
        @Override
        public void onPageFinished(WebView view,
                                   String url) {
            super.onPageFinished(view, url);
            // These javascript operations are responsible for MRAID ad's initialization
                String jsScript = "mraid.sdk.state = 'default';mraid.sdk.ready();";
                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) {
                    view.evaluateJavascript(jsScript, null);
                }
                else {
                    view.loadUrl("javascript:"+jsScript);
                }
        }
    });
}

@Override
public void onViewCreated(View view,
                          Bundle savedInstanceState) {
    // Imagine that your AdView was added to activity's xml file
    mAdSpace = (AdView) view.findViewById(R.id.cxenseView1);
    // Set your own WebClient's implementation that can initialize MRAID ad's state
    mAdSpace.setWebViewClient(new ImageCachingWebViewClient() {
        @Override
        public void onPageFinished(WebView view,
                                   String url) {
            super.onPageFinished(view, url);
            // These javascript operations are responsible for MRAID ad's initialization
            String jsScript = "mraid.sdk.state = 'default';mraid.sdk.ready();";
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) {
                view.evaluateJavascript(jsScript, null);
            }
            else {
                view.loadUrl("javascript:"+jsScript);
            }
        }
    });
}

// Imagine that '_adview' is a reference to CxenseAdView in your ViewController
_adview.adWebView.webView.delegate = self;
 
// After that, you can implement '-[UIWebViewDelegate webViewDidFinishLoad:]' in your ViewController:
- (void)webViewDidFinishLoad:(UIWebView *)webView {
    [_adview.adWebView.webView stringByEvaluatingJavaScriptFromString:@"mraid.sdk.state = 'default'; mraid.sdk.ready();"];
}

Step 2. Interacting with MRAID-compliant ad 

On that stage - you already have small bridge with for building own custom interactions with the ad. For example, that how your application can report information about container's visibility to the ad using 'viewableChange' event (see MRAID specification for details): 

webView.evaluateJavascript("mraid.setViewable(true);", null);

[webView stringByEvaluatingJavaScriptFromString:@"mraid.setViewable(true);"];

Questions?

 In case of any questions please don't hesitate to ask support@cxense.com.

Last updated: January 19, 2022