Interstitial Ads

Interstitial ads provide full-screen experiences, commonly incorporating rich media to offer a higher level of interactivity compared to banner ads. Interstitials are typically shown during natural transitions in your app, e.g. after completing a game level, or while waiting for a new view to load. You can use the MoPubInterstitial object and its associated listeners to fetch and display interstitial ads in your app.

Prerequisites

Before integrating interstitial ads in your app, you’ll need to go through the steps in our Getting Started to create an account on MoPub and integrate the SDK into your project.

Sample code

For a complete example of how to add interstitial ads into your app, check out the mopub-sample.

Load interstitial ads in your app

1. Check your AndroidManifest.xml file

Be sure you have the following permissions:

<!-- Required permissions -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Optional permissions. Will pass Lat/Lon values when available. Choose either Coarse or Fine -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

<!-- Optional permissions. Used for MRAID 2.0 storePicture ads -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION are only needed if you want the device to automatically send the user’s location for targeting. WRITE_EXTERNAL_STORAGE is optional and only required for MRAID 2.0 store picture ads.

You’ll also need to include the following custom Activities (even though you won’t instantiate them directly):

<activity android:name="com.mopub.mobileads.MoPubActivity" android:configChanges="keyboardHidden|orientation|screenSize"/>
<activity android:name="com.mopub.mobileads.MraidActivity" android:configChanges="keyboardHidden|orientation|screenSize"/>
<activity android:name="com.mopub.common.MoPubBrowser" android:configChanges="keyboardHidden|orientation|screenSize"/>

2. Create and display an interstitial ad

The MoPub SDK provides a custom class, MoPubInterstitial, 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 a MoPubInterstitial instance variable:

private MoPubInterstitial mInterstitial;

MoPubInterstitial provides a listener interface, InterstitialAdListener, which you’ll use to stay informed about ad lifecycle events. Make sure your Activity implements the InterstitialAdListener interface.

In your Activity’s onCreate() method, instantiate the MoPubInterstitial using the context and the Ad Unit ID you created in the Getting Started.

mInterstitial = new MoPubInterstitial(this, YOUR_INTERSTITIAL_AD_UNIT_ID_HERE);

Next, register your activity as the InterstitialAdListener:

// Remember that "this" refers to your current activity.
mInterstitial.setInterstitialAdListener(this);

Now you’re ready to display an ad. Displaying the ad takes four 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 media and may take some time to load. We suggest 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 InterstitialAdListener callbacks) before calling show().

  1. When you’re ready to display your ad, use InterstitialAdListener#onInterstitialLoaded() callback and the MoPubInterstitial.isReady() to check whether the interstitial was successfully cached.

  2. If isReady() returns true, display the interstitial by calling the show() method. You can add logic to the other interstitial lifecycle methods to handle what should happen when your user interacts with the ad– e.g. resuming your game onInterstitialDismissed().

  3. Lastly, remember to call destroy() on the interstitial in your Activity’s onDestroy method.

  4. Your completed Activity code should look something like this:

     public class ExampleActivity extends Activity implements InterstitialAdListener {
         MoPubInterstitial mInterstitial;
    
         @Override
         protected void onCreate(Bundle savedInstanceState) {
             super.onCreate(savedInstanceState);
             setContentView(R.layout.main);
             mInterstitial = new MoPubInterstitial(this, YOUR_INTERSTITIAL_AD_UNIT_ID_HERE);
             mInterstitial.setInterstitialAdListener(this);
             mInterstitial.load();
         }
    
         @Override
         protected void onDestroy() {
             mInterstitial.destroy();
             super.onDestroy();
         }
    
         // Defined by your application, indicating that you're ready to show an interstitial ad.
         void yourAppsShowInterstitialMethod() {
        		if (mInterstitial.isReady()) {
        			mInterstitial.show();
        		} else {
        			// Caching is likely already in progress if `isReady()` is false.
        			// Avoid calling `load()` here and instead rely on the callbacks as suggested below.
        		}
        	}
    
         // InterstitialAdListener methods
         @Override
         public void onInterstitialLoaded(MoPubInterstitial interstitial) {
             // The interstitial has been cached and is ready to be shown.
         }
    
         @Override
         public void onInterstitialFailed(MoPubInterstitial interstitial, MoPubErrorCode errorCode) {
         	// The interstitial has failed to load. Inspect errorCode for additional information.
         }
    
         @Override
         public void onInterstitialShown(MoPubInterstitial interstitial) {
         	// The interstitial has been shown. Pause / save state accordingly.
         }
    
         @Override
         public void onInterstitialClicked(MoPubInterstitial interstitial) {}
    
         @Override
         public void onInterstitialDismissed(MoPubInterstitial interstitial) {
         	// The interstitial has being dismissed. Resume / load state accordingly.
         }
     }
    

See InterstitialDetailFragment.java from mopub-sample for a full example.

Best Practices

Mediation SDKs might rely on select Activity lifecycle events for tracking purposes. For the SDKs that do, you are required to notify MoPub of when those events happen, so that MoPub can pass them onto mediated networks, like so:

    @Override
    protected void onPause() {
        super.onPause();
        MoPub.onPause(this);
    }

    @Override
    protected void onStop() {
        super.onStop();
        MoPub.onStop(this);
    }

    @Override
    protected void onResume() {
        super.onResume();
        MoPub.onResume(this);
    }

    // Additional lifecycle events

Last updated October 10, 2018

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2018 MoPub Inc.