You are here: Developers > OpenX Mobile Android SDK > Interstitial integration

Interstitial integration

Last updated on October 4, 2017

Overview

Prerequisites

Sample code

Loading interstitial ads in your app

Using AdEventsListener

Data enrichment

Setting a custom "Close" image

Setting background opacity

Prerequisites

  1. Before integrating interstitialA full-screen ad displayed in content transitions. For example, a video ad that loads between levels of a mobile game. ads in your app, you’ll need to create a mobile ad unit or make sure you know which existing ad unitThe smallest inventory component that represents the space on a site where ads display. to use.
  2. Update your Android manifest, as described in Android SDK integration.

Sample code

For a complete example, please see InterstitialActivity.java in the AndroidSDKDemo workspace provided in the SDK zip file.

Loading interstitial ads in your app

  1. Create and display an interstitial ad.
  2. The OpenX Mobile Android SDK provides a custom class, AdView, that handles fetching and displaying fullscreen interstitial ads. To ensure a smooth experience, you should pre-fetch the content as soon as your Activity is created, then display it if the fetch was successful.

    In the Activity in which you want to show the interstitial ad, declare an Adview instance variable:

    
    private AdView adView;

  3. (Optional) Add a listener and implement those callbacks for the notification for various events.

    In your Activity’s onCreate() method, instantiate the AdView using the context and the ad unit ID you created in the OpenX user interface.

    adView = new AdView(this, adDetails.adDomain, adDetails.adId, AdConfiguration.AdUnitIdentifierType.INTERSTITIAL);
  4. Next, register your activity as the AdEventsListener:

    //Remember that "this" refers to your current activity. 
    adView.addAdEventListener(this);
    //where adView is an instance of AdView.
    //this - the class implementing AdEventsListener.
    					
  5. Now you're ready to display an ad. Displaying the ad involves these steps:

    1. In your onCreate() method, call load() to begin caching the ad. It’s important to fetch interstitial ad content well before you plan to show it, since it often incorporates rich mediaAd technology that features more refined images as well as audio and video in the ad. Rich media ads frequently allow visitors to interact with a banner without leaving the page on which it appears (e.g., movie ads that expand and play a trailer on the host page). and may take some time to load. OpenX recommends caching when your Activity is first created, but you may also choose to do it based on events in your app, like beginning a game level.

      Note: The load() method will take a few seconds, as it requests and caches ad content, including JavaScript, images, and additional resources. As a best practice, provide sufficient time (by waiting for the appropriate AdEventsListener callbacks, in this case, adDidLoad()) before calling show().

    2. When you’re ready to display your ad, use AdEventsListener#adDidLoad() callback to check whether the returned adView is not null.

    3. If the returned adView is not null, display the interstitial by calling the showAsInterstitialFromRoot() method. You can add logic to the other interstitial life cycle methods to handle what should happen when your user interacts with the ad, for example, resuming your game on ad dismissal through adInterstitialDidClose().

    4. Call destroy() on the interstitial in your Activity’s onDestroy() method.

      Your completed Activity code should look something like this:

      
      private void createInterstitialAD() {
       
      	try {
      		//Create an interstitial ad.
      		adView = new AdView(this, adDetails.adDomain, adDetails.adId, AdConfiguration.AdUnitIdentifierType.INTERSTITIAL);
      	}
      	catch (Exception e) {
      		Log.e(TAG, "AdView creation failed");
      	}
       
      	if (adView != null) {
      		/* Set auto display false, so interstitial ad is prefetched and can be used later. */
      		adView.setAutoDisplayOnLoad(false);
      		//Listener to get the life cycle events of an ad.
      		adView.addAdEventListener(this);
       
      		//Properties to fix the position and an image for a custom close view
      		adView.interstitialProperties.customClosePosition = InterstitialManager.InterstitialClosePosition.TOP_RIGHT;
      		adView.interstitialProperties.customCloseDrawable = getResources().getDrawable(android.R.drawable.ic_delete);
       
      		//Sets the opacity of the ad. Recommended 1.0f.
      		adView.interstitialProperties.setPubBackGroundOpacity(1.0f);
       
      		UserParameters userParameters = new UserParameters();
      		userParameters.setUserGender(UserParameters.OXMGender.FEMALE);
      		//Set extra params for data enrichment.
      		adView.setUserParameters(userParameters);
       
      		//Set flex ad sizes.
      		adView.setFlexAdSize(AdConfiguration.OXMAdSize.INTERSTITIAL_320x480_300x250);
       
      		//Load an ad.
      		adView.load();
      	}
      }
      				

See InterstitialActivity.java from AndroidSDKDemo for a full example.

Using AdEventsListener

For interstitial ads, an events listener must always be implemented and set before the load() method is called, and the showAsInterstitialFromRoot() method must always be called after the onAdDidLoad() event is fired. For details on available events, see Callbacks.


@Override
public void adDidLoad(final AdView adView, AdDetails adDetails) {
Log.d(TAG, "Ad Loaded");
 
	btnShowInterstitial.setEnabled(true);
	btnShowInterstitial.setText("Show Interstitial");
	btnShowInterstitial.setOnClickListener(new OnClickListener() {
 
		@Override
		public void onClick(View v) {
			adView.showAsInterstitialFromRoot();
		}
	});
}

AdDetails includes a transactionId. The transactionId is a unique identifier for an ad, which you can use for managing and reporting ad quality issues.

Data enrichment

See Request parameters for details on parameters you can include to enrich data in the ad requestCommunication from a web browser or app to an ad server to display an ad..

Setting a custom "Close" image

By default, an image is shown on the top-right corner of an interstitial ad to allow the user to close the ad:

Close

You can choose a custom Close image using AdView's interstitialProperties methods.

//Properties to fix the position and an image for a custom close view.
 adView.interstitialProperties.customClosePosition = InterstitialManager.InterstitialClosePosition.TOP_RIGHT
 adView.interstitialProperties.customCloseDrawable = getResources().getDrawable(android.R.drawable.ic_delete);
        

Setting background opacity

You can use setBackgroundOpacity to set the dim amount for the background of the interstitial ad. The recommended setting is 1.0f:


adView.setBackgroundOpacity(1.0f);

Feedback form