Interstitial (legacy API)

Warning: This guide covers the interstitial API as it existed prior to 19.7.0. Please read the migration guide for more details on the changes introduced in version 19.7.0 and finalized in 20.0.0.

Interstitial ads are full-screen ads that cover the interface of their host app. They're typically displayed at natural transition points in the flow of an app, such as between activities or during the pause between levels in a game. When an app shows an interstitial ad, the user has the choice to either tap on the ad and continue to its destination or close it and return to the app. Case study.

This guide explains how to integrate interstitial ads into an Android app.

Prerequisite

• Import the Google Mobile Ads SDK, either by itself or as part of Firebase.

Create an interstitial ad object

Interstitial ads are requested and shown by InterstitialAd objects. The first step is instantiating InterstitialAd and setting its ad unit ID. This is done in the onCreate() method of an Activity:

Java

package ...

import com.google.android.gms.ads.InterstitialAd;

public class MainActivity extends Activity {

    private InterstitialAd mInterstitialAd;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        MobileAds.initialize(this, new OnInitializationCompleteListener() {
            @Override
            public void onInitializationComplete(InitializationStatus initializationStatus) {}
        });

        mInterstitialAd = new InterstitialAd(this);
        mInterstitialAd.setAdUnitId("ca-app-pub-3940256099942544/1033173712");
    }
}

Kotlin

class MainActivity : Activity() {

    private lateinit var mInterstitialAd: InterstitialAd

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        MobileAds.initialize(this) {}

        mInterstitialAd = InterstitialAd(this)
        mInterstitialAd.adUnitId = "ca-app-pub-3940256099942544/1033173712"
    }
}

A single InterstitialAd object can be used to request and display multiple interstitial ads over the course of an activity's lifespan, so you only need to construct it once.

Always test with test ads

When building and testing your apps, make sure you use test ads rather than live, production ads. Failure to do so can lead to suspension of your account.

The easiest way to load test ads is to use our dedicated test ad unit ID for Android interstitials:

ca-app-pub-3940256099942544/1033173712

It's been specially configured to return test ads for every request, and you're free to use it in your own apps while coding, testing, and debugging. Just make sure you replace it with your own ad unit ID before publishing your app.

For more information about how the Mobile Ads SDK's test ads work, see Test Ads.

Load an ad

Note: Make all calls to the Mobile Ads SDK on the main thread.

To load an interstitial ad, call the InterstitialAd object's loadAd() method. This method accepts an AdRequest object as its single parameter:

Java

package ...

import com.google.android.gms.ads.AdRequest;
import com.google.android.gms.ads.InterstitialAd;

public class MainActivity extends Activity {

    private InterstitialAd mInterstitialAd;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        MobileAds.initialize(this,
            "ca-app-pub-3940256099942544~3347511713");

        mInterstitialAd = new InterstitialAd(this);
        mInterstitialAd.setAdUnitId("ca-app-pub-3940256099942544/1033173712");
        mInterstitialAd.loadAd(new AdRequest.Builder().build());
    }
}

Kotlin

class MainActivity : Activity() {

    private lateinit var mInterstitialAd: InterstitialAd

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        MobileAds.initialize(this,
            "ca-app-pub-3940256099942544~3347511713")

        mInterstitialAd = InterstitialAd(this)
        mInterstitialAd.adUnitId = "ca-app-pub-3940256099942544/1033173712"
        mInterstitialAd.loadAd(AdRequest.Builder().build())
    }
}

Show the ad

Interstitial ads should be displayed during natural pauses in the flow of an app. Between levels of a game is a good example, or after the user completes a task. To show an interstitial, use the isLoaded() method to verify that it's done loading, then call show(). The interstitial ad from the previous code example could be shown in a button's OnClickListener like this:

Java

mMyButton.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        if (mInterstitialAd.isLoaded()) {
            mInterstitialAd.show();
        } else {
            Log.d("TAG", "The interstitial wasn't loaded yet.");
        }
    }
});

Kotlin

mMyButton.setOnClickListener {
    if (mInterstitialAd.isLoaded) {
        mInterstitialAd.show()
    } else {
        Log.d("TAG", "The interstitial wasn't loaded yet.")
    }
}

Ad events

To further customize the behavior of your ad, you can hook onto a number of events in the ad's lifecycle: loading, opening, closing, and so on. You can listen for these events through the AdListener class.

To use an AdListener with an InterstitialAd object, simply call the setAdListener() method:

Java

mInterstitialAd.setAdListener(new AdListener() {
    @Override
    public void onAdLoaded() {
        // Code to be executed when an ad finishes loading.
    }

    @Override
    public void onAdFailedToLoad(LoadAdError adError) {
        // Code to be executed when an ad request fails.
    }

    @Override
    public void onAdOpened() {
        // Code to be executed when the ad is displayed.
    }

    @Override
    public void onAdClicked() {
        // Code to be executed when the user clicks on an ad.
    }

    @Override
    public void onAdLeftApplication() {
        // Code to be executed when the user has left the app.
    }

    @Override
    public void onAdClosed() {
        // Code to be executed when the interstitial ad is closed.
    }
});

Kotlin

mInterstitialAd.adListener = object: AdListener() {
    override fun onAdLoaded() {
        // Code to be executed when an ad finishes loading.
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {
        // Code to be executed when an ad request fails.
    }

    override fun onAdOpened() {
        // Code to be executed when the ad is displayed.
    }

    override fun onAdClicked() {
        // Code to be executed when the user clicks on an ad.
    }

    override fun onAdLeftApplication() {
        // Code to be executed when the user has left the app.
    }

    override fun onAdClosed() {
        // Code to be executed when the interstitial ad is closed.
    }
}

Each of the overridable methods in AdListener corresponds to an event in the lifecycle of an ad.

Overridable methods
onAdLoaded()	The onAdLoaded() method is executed when an ad has finished loading.
onAdFailedToLoad()	The onAdFailedToLoad() method is the only one that includes a parameter. The error parameter of type LoadAdError describes what error occurred. For more information, refer to the Debugging Ad Load Errors documentation.
onAdOpened()	This method is invoked when the ad is displayed, covering the device's screen.
onAdLeftApplication()	This method is invoked when a user click opens another app (such as the Google Play), backgrounding the current app.
onAdClosed()	This method is invoked when the interstitial ad is closed due to the user tapping on the close button. If your app paused its audio output or game loop, this is a great place to resume it.

Warning: Attempting to load a new ad from the onAdFailedToLoad() method is strongly discouraged. If you must load an ad from onAdFailedToLoad(), limit ad load retries to avoid continuous failed ad requests in situations such as limited network connectivity.

Using an AdListener to reload

The AdListener class's onAdClosed() method is a handy place to load a new interstitial after displaying the previous one:

Java

...
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

        MobileAds.initialize(this,
            "ca-app-pub-3940256099942544~3347511713");

    mInterstitialAd = new InterstitialAd(this);
    mInterstitialAd.setAdUnitId("ca-app-pub-3940256099942544/1033173712");
    mInterstitialAd.loadAd(new AdRequest.Builder().build());

    mInterstitialAd.setAdListener(new AdListener() {
        @Override
        public void onAdClosed() {
            // Load the next interstitial.
            mInterstitialAd.loadAd(new AdRequest.Builder().build());
        }

    });
}
...

Kotlin

...
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

        MobileAds.initialize(this,
            "ca-app-pub-3940256099942544~3347511713")

    mInterstitialAd = InterstitialAd(this)
    mInterstitialAd.adUnitId = "ca-app-pub-3940256099942544/1033173712"
    mInterstitialAd.adListener = object : AdListener() {
        override fun onAdClosed() {
            mInterstitialAd.loadAd(AdRequest.Builder().build())
        }
    }
}
...

Some best practices

Consider whether interstitial ads are the right type of ad for your app.

Interstitial ads work best in apps with natural transition points. The conclusion of a task within an app, like sharing an image or completing a game level, creates such a point. Because the user is expecting a break in the action, it's easy to present an interstitial ad without disrupting their experience. Make sure you consider at which points in your app's workflow you'll display interstitial ads and how the user is likely to respond.

Remember to pause the action when displaying an interstitial ad.

There are a number of different types of interstitial ads: text, image, video, and more. It's important to make sure that when your app displays an interstitial ad, it also suspends its use of some resources to allow the ad to take advantage of them. For example, when you make the call to display an interstitial ad, be sure to pause any audio output being produced by your app. You can resume playing sounds in the onAdClosed() event handler, which will be invoked when the user has finished interacting with the ad. In addition, consider temporarily halting any intense computation tasks (such as a game loop) while the ad is being displayed. This will make sure the user doesn't experience slow or unresponsive graphics or stuttered video.

Allow for adequate loading time.

Just as it's important to make sure you display interstitial ads at an appropriate time, it's also important to make sure the user doesn't have to wait for them to load. Loading the ad in advance by calling loadAd() before you intend to call show() can ensure that your app has a fully loaded interstitial ad at the ready when the time comes to display one.

Don't flood the user with ads.

While increasing the frequency of interstitial ads in your app might seem like a great way to increase revenue, it can also degrade the user experience and lower clickthrough rates. Make sure that users aren't so frequently interrupted that they're no longer able to enjoy the use of your app.

Source code

MyActivity.java

/*
 * Copyright (C) 2013 Google, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.google.android.gms.example.interstitialexample;

import android.os.Bundle;
import android.os.CountDownTimer;
import android.support.v7.app.AppCompatActivity;
import android.view.View;
import android.widget.Button;
import android.widget.TextView;
import android.widget.Toast;
import com.google.android.gms.ads.AdListener;
import com.google.android.gms.ads.AdRequest;
import com.google.android.gms.ads.InterstitialAd;
import com.google.android.gms.ads.LoadAdError;
import com.google.android.gms.ads.MobileAds;
import com.google.android.gms.ads.initialization.InitializationStatus;
import com.google.android.gms.ads.initialization.OnInitializationCompleteListener;

/**
 * Main Activity. Inflates main activity xml.
 */
public class MyActivity extends AppCompatActivity {

    private static final long GAME_LENGTH_MILLISECONDS = 3000;
    private static final String AD_UNIT_ID = "ca-app-pub-3940256099942544/1033173712";

    private InterstitialAd interstitialAd;
    private CountDownTimer countDownTimer;
    private Button retryButton;
    private boolean gameIsInProgress;
    private long timerMilliseconds;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_my);

        // Initialize the Mobile Ads SDK.
        MobileAds.initialize(this, new OnInitializationCompleteListener() {
            @Override
            public void onInitializationComplete(InitializationStatus initializationStatus) {}
        });

        // Create the InterstitialAd and set the adUnitId.
        interstitialAd = new InterstitialAd(this);
        // Defined in res/values/strings.xml
        interstitialAd.setAdUnitId(AD_UNIT_ID);

    interstitialAd.setAdListener(
        new AdListener() {
          @Override
          public void onAdLoaded() {
            Toast.makeText(MyActivity.this, "onAdLoaded()", Toast.LENGTH_SHORT).show();
          }

          @Override
          public void onAdFailedToLoad(LoadAdError loadAdError) {
            String error =
                String.format(
                    "domain: %s, code: %d, message: %s",
                    loadAdError.getDomain(), loadAdError.getCode(), loadAdError.getMessage());
            Toast.makeText(
                    MyActivity.this, "onAdFailedToLoad() with error: " + error, Toast.LENGTH_SHORT)
                .show();
          }

          @Override
          public void onAdClosed() {
            startGame();
          }
        });

        // Create the "retry" button, which tries to show an interstitial between game plays.
        retryButton = findViewById(R.id.retry_button);
        retryButton.setVisibility(View.INVISIBLE);
        retryButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View view) {
                showInterstitial();
            }
        });

        startGame();
    }

    private void createTimer(final long milliseconds) {
        // Create the game timer, which counts down to the end of the level
        // and shows the "retry" button.
        if (countDownTimer != null) {
            countDownTimer.cancel();
        }

        final TextView textView = findViewById(R.id.timer);

        countDownTimer = new CountDownTimer(milliseconds, 50) {
            @Override
            public void onTick(long millisUnitFinished) {
                timerMilliseconds = millisUnitFinished;
                textView.setText("seconds remaining: " + ((millisUnitFinished / 1000) + 1));
            }

            @Override
            public void onFinish() {
                gameIsInProgress = false;
                textView.setText("done!");
                retryButton.setVisibility(View.VISIBLE);
            }
        };
    }

    @Override
    public void onResume() {
        // Start or resume the game.
        super.onResume();

        if (gameIsInProgress) {
            resumeGame(timerMilliseconds);
        }
    }

    @Override
    public void onPause() {
        // Cancel the timer if the game is paused.
        countDownTimer.cancel();
        super.onPause();
    }

    private void showInterstitial() {
        // Show the ad if it's ready. Otherwise toast and restart the game.
        if (interstitialAd != null && interstitialAd.isLoaded()) {
            interstitialAd.show();
        } else {
            Toast.makeText(this, "Ad did not load", Toast.LENGTH_SHORT).show();
            startGame();
        }
    }

    private void startGame() {
        // Request a new ad if one isn't already loaded, hide the button, and kick off the timer.
        if (!interstitialAd.isLoading() && !interstitialAd.isLoaded()) {
            AdRequest adRequest = new AdRequest.Builder().build();
            interstitialAd.loadAd(adRequest);
        }

        retryButton.setVisibility(View.INVISIBLE);
        resumeGame(GAME_LENGTH_MILLISECONDS);
    }

    private void resumeGame(long milliseconds) {
        // Create a new timer for the correct length and start it.
        gameIsInProgress = true;
        timerMilliseconds = milliseconds;
        createTimer(milliseconds);
        countDownTimer.start();
    }
}

MainActivity.kt

package com.google.android.gms.example.interstitialexample

import android.os.Bundle
import android.os.CountDownTimer
import android.view.View
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import com.google.android.gms.ads.AdListener
import com.google.android.gms.ads.AdRequest
import com.google.android.gms.ads.InterstitialAd
import com.google.android.gms.ads.LoadAdError
import com.google.android.gms.ads.MobileAds
import com.google.android.gms.ads.RequestConfiguration
import kotlinx.android.synthetic.main.activity_main.*

const val GAME_LENGTH_MILLISECONDS = 3000L
const val AD_UNIT_ID = "ca-app-pub-3940256099942544/1033173712"

class MainActivity : AppCompatActivity() {

  private lateinit var mInterstitialAd: InterstitialAd
  private var mCountDownTimer: CountDownTimer? = null
  private var mGameIsInProgress = false
  private var mTimerMilliseconds = 0L

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    // Initialize the Mobile Ads SDK.
    MobileAds.initialize(this) {}

    // Set your test devices. Check your logcat output for the hashed device ID to
    // get test ads on a physical device. e.g.
    // "Use RequestConfiguration.Builder().setTestDeviceIds(Arrays.asList("ABCDEF012345"))
    // to get test ads on this device."
    MobileAds.setRequestConfiguration(
      RequestConfiguration.Builder()
        .setTestDeviceIds(listOf("ABCDEF012345"))
        .build()
    )

    // Create the InterstitialAd and set it up.
    mInterstitialAd = InterstitialAd(this).apply {
      adUnitId = AD_UNIT_ID
      adListener = (
        object : AdListener() {
          override fun onAdLoaded() {
            Toast.makeText(this@MainActivity, "onAdLoaded()", Toast.LENGTH_SHORT).show()
          }

          override fun onAdFailedToLoad(loadAdError: LoadAdError) {
            val error = "domain: ${loadAdError.domain}, code: ${loadAdError.code}, " +
              "message: ${loadAdError.message}"
            Toast.makeText(
              this@MainActivity,
              "onAdFailedToLoad() with error $error",
              Toast.LENGTH_SHORT
            ).show()
          }

          override fun onAdClosed() {
            startGame()
          }
        }
      )
    }

    // Create the "retry" button, which triggers an interstitial between game plays.
    retry_button.visibility = View.INVISIBLE
    retry_button.setOnClickListener { showInterstitial() }

    // Kick off the first play of the "game."
    startGame()
  }

  // Create the game timer, which counts down to the end of the level
  // and shows the "retry" button.
  private fun createTimer(milliseconds: Long) {
    mCountDownTimer?.cancel()

    mCountDownTimer = object : CountDownTimer(milliseconds, 50) {
      override fun onTick(millisUntilFinished: Long) {
        mTimerMilliseconds = millisUntilFinished
        timer.text = "seconds remaining: ${ millisUntilFinished / 1000 + 1 }"
      }

      override fun onFinish() {
        mGameIsInProgress = false
        timer.text = "done!"
        retry_button.visibility = View.VISIBLE
      }
    }
  }

  // Show the ad if it's ready. Otherwise toast and restart the game.
  private fun showInterstitial() {
    if (mInterstitialAd.isLoaded) {
      mInterstitialAd.show()
    } else {
      Toast.makeText(this, "Ad wasn't loaded.", Toast.LENGTH_SHORT).show()
      startGame()
    }
  }

  // Request a new ad if one isn't already loaded, hide the button, and kick off the timer.
  private fun startGame() {
    if (!mInterstitialAd.isLoading && !mInterstitialAd.isLoaded) {
      // Create an ad request.
      val adRequest = AdRequest.Builder().build()

      mInterstitialAd.loadAd(adRequest)
    }

    retry_button.visibility = View.INVISIBLE
    resumeGame(GAME_LENGTH_MILLISECONDS)
  }

  private fun resumeGame(milliseconds: Long) {
    // Create a new timer for the correct length and start it.
    mGameIsInProgress = true
    mTimerMilliseconds = milliseconds
    createTimer(milliseconds)
    mCountDownTimer?.start()
  }

  // Resume the game if it's in progress.
  public override fun onResume() {
    super.onResume()

    if (mGameIsInProgress) {
      resumeGame(mTimerMilliseconds)
    }
  }

  // Cancel the timer if the game is paused.
  public override fun onPause() {
    mCountDownTimer?.cancel()
    super.onPause()
  }
}

Additional resources

Samples on GitHub

• Interstitial sample app: Java | Kotlin

Mobile Ads Garage video tutorials

• Interstitial implementation
• Interstitial best practices

Success stories

• Sample use case

Next steps

• If you haven't already, create your own interstitial ad unit in the AdMob UI.
• Learn about ad targeting and interstitial ad guidance.
• Try another ad format:
  • Banner
  • Rewarded Video
  • Native