Interstitial ads

  • The Google Mobile Ads C++ SDK is deprecated as of June 17, 2024, and should not be adopted for new projects, with end-of-maintenance on June 17, 2025.

  • Interstitial ads are full-screen ads displayed at natural transition points in an app flow.

  • Always test with dedicated test ad unit IDs provided for Android and iOS to avoid account suspension.

  • Implementing interstitial ads involves configuring, loading, registering for callbacks, and displaying the ad.

  • Best practices for using interstitial ads include displaying them at appropriate transition points, pausing app activity, allowing adequate loading time, and avoiding excessive ad frequency.


Interstitial ads are full-screen ads that cover the interface of an app until closed by the user. 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 shows you how to integrate interstitial ads into Android and iOS apps using the Google Mobile Ads C++ SDK.

Prerequisites

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 interstitials, which varies per device platform:

  • Android: ca-app-pub-3940256099942544/1033173712
  • iOS: ca-app-pub-3940256099942544/4411468910

They've 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.

Implementation

The main steps to integrate interstitial ads are:

  1. Load an ad.
  2. Register for callbacks.
  3. Display the ad and handle its lifecycle events.

Configure an InterstitialAd

Interstitial ads are displayed in InterstitialAd objects, so the first step toward integrating interstitial ads into your app is to create and initialize an InterstitialAd object.

  1. Add the following header to your app's C++ code: 

     #include "firebase/gma/interstial_ad.h"

  2. Declare and instantiate an InterstitialAd object: 

     firebase::gma::InterstitialAd* interstitial_ad;
 interstitial_ad = new firebase::gma::InterstitialAd();

  3. Initialize the InterstitialAd instance using your parent view cast to an AdParent type. The parent view is a JNI jobject reference to an Android Activity or a pointer to an iOS UIView.

    // my_ad_parent is a jobject reference to an Android Activity or
// a pointer to an iOS UIView.
firebase::gma::AdParent ad_parent =
  static_cast<firebase::gma::AdParent>(my_ad_parent);
firebase::Future<void> result = interstitial_ad->Initialize(ad_parent);

  4. As an alternative to retaining the future as a variable, you can periodically check the status of the initialization operation by invoking InitializeLastResult() on the InterstitialAd object. This may be helpful for keeping track of the initialization process in your global game loop.

    // Monitor the status of the future in your game loop:
firebase::Future<void> result = interstitial_ad->InitializeLastResult();
if (result.status() == firebase::kFutureStatusComplete) {
  // Initialization completed.
  if(future.error() == firebase::gma::kAdErrorCodeNone) {
    // Initialization successful.
  } else {
    // An error has occurred.
  }
} else {
  // Initialization on-going.
}

For more information about working with firebase::Future, see Use Futures to monitor the completion status of method calls.

Load an ad

Loading an ad is accomplished using the LoadAd() method on the InterstitialAd object. The load method requires that you've initialized the InterstitialAd object, and that you have your ad unit ID and an AdRequest object. A firebase::Future is returned which you can use to monitor the state and result of the load operation.

The following code shows how to load an ad once the InterstitialAd has been successfully initialized:

firebase::gma::AdRequest ad_request;
firebase::Future<firebase::gma::AdResult> load_ad_result;
load_ad_result = interstitial_ad->LoadAd(interstitial_ad_unit_id, ad_request);

Register for callbacks

You must extend the FullScreenContentListener class in order to receive notifications of interstitial ad presentation and lifecycle events. Your custom FullScreenContentListener subclass can be registered through the InterstitialAd::SetFullScreenContentListener() method, and it will receive callbacks when the ad presents successfully or unsuccessfully as well as when it's dismissed.

The following code shows how to extend the class and assign it to the ad: