Interstitial Ads

• Prerequisites
• Load Interstitial Ads in Your App
• Sample Code
• Best Practices

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; for example, after completing a game level, or while waiting for a new view to load. Use the MoPubInterstitial object and its associated listeners to fetch and display interstitial ads in your app.

Prerequisites

1. Go through the steps in our Getting Started Guide to create an account on MoPub and integrate the SDK into your project. It is essential that you added the necessary Activities to your AndroidManifest.xml file as instructed.

2. Add any other activities as required by mediated SDKs you are adding. For additional details, check the respective network guides.

3. Create an ad unit in the Publisher UI. You will need that ad unit’s ID.

Load Interstitial Ads in Your App

To be safe, once again check your AndroidManifest.xml file to make sure you included the necessary custom Activities we discussed in the Prerequisites section (even though you won’t instantiate them directly).

After that, loading interstitial ads is a two-step process:

1. Create an interstitial ad
2. Display an interstitial ad

Step 1. Create 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.

1. In the Activity in which you want to show the interstitial ad, declare a MoPubInterstitial instance variable:

   private MoPubInterstitial mInterstitial;
   

2. 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.

3. 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);
   

4. Next, register your activity as the InterstitialAdListener:

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

Step 2. Display an Interstitial Ad

Now you’re ready to display an ad:

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, because 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, such as the start of 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().

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

3. 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; for example, resuming your game on onInterstitialDismissed().

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

5. Your completed Activity code should look something like this (see InterstitialDetailFragment.java from mopub-sample for a full example):

    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.
        }
    }
   

Sample Code

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

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