Set up interstitial ads

Select platform: Android iOS Unity Flutter Android (Legacy)

Interstitial ads are full-screen ads that cover the app interface. You display these ads at natural transition points in your app, such as between activities or during pauses in game levels.

When your app shows an interstitial ad, your users can either tap on the ad and continue, or close the ad and return to the app. Read one of our case studies.

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

Before you begin

Before you continue, do the following:

  • Set up GMA Next-Gen SDK.
  • Use the test interstitial ad unit ID ca-app-pub-3940256099942544/1033173712.
    • When building and testing your app, make sure that you use test ads rather than live, production ads. If you don't use the test ad unit ID, Google can suspend your account.
    • Before you publish your app, replace this ID with your ad unit ID.
    • For details on GMA Next-Gen SDK test ads, see Enable test ads.

Understand ad preloading

Ad preloading in GMA Next-Gen SDK automates ad loading and caching.

Ad preloading provides the following benefits:

  • Reference management: maintains references until ads are shown.
  • Automatic reloading: loads a new ad when one is retrieved from the cache.
  • Managed retries: loads a new ad when one fails to load.
  • Expiration handling: refreshes ads before expiring.
  • Cache optimization: optimizes the cache order to deliver the highest priority ad.

Start ad preloading

To begin preloading ads, call the startPreload() method once at app start. After you call the startPreload() method, GMA Next-Gen SDK automatically preloads ads and retries failed requests for preloaded configurations.

The following example shows how to start preloading ads:

Kotlin

// Call start() once after SDK initialization.
// Preload only one ad unit per format to optimize performance.
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
InterstitialAdPreloader.start(adUnitId, preloadConfig)

Java

// Call start() once after SDK initialization.
// Preload only one ad unit per format to optimize performance.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
InterstitialAdPreloader.start(adUnitId, preloadConfig);

Replace AD_UNIT_ID with your ad unit ID.

The previous example shows how to use the ad unit ID as the preload ID. A preload ID is a string identifier that you create to identify an ad preloading configuration. If your app requires multiple targeting configurations for the same ad unit ID, pass a custom string identifier.

Get and show the preloaded ad

When you want to show an ad, call the pollAd() method. GMA Next-Gen SDK retrieves an available ad and automatically preloads the next ad in the background. If no ad is available, GMA Next-Gen SDK returns no ads.

When you have an available ad object, call the show method to display the ad. The following example shows how to retrieve and show a preloaded ad:

Kotlin

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = InterstitialAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : InterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Interstitial ad recorded an impression.")
      }
    }
  ad.show(activity)
}

Java

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  final InterstitialAd ad = InterstitialAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "Interstitial ad is not available.");
    return;
  }

  Log.d(TAG, "Interstitial ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new InterstitialAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Interstitial ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(activity);
}

Avoid calling the pollAd() method until you are ready to show an ad. To read the ad response info without showing it, see Read the response info.

Listen to ad events

Before showing the ad, listen to ad events. The following example shows how to register callbacks for ad events:

Kotlin

// Listen for ad events.
val ad = interstitialAd
if (ad == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.")
  return
}

ad.adEventCallback =
  object : InterstitialAdEventCallback {
    override fun onAdShowedFullScreenContent() {
      // Interstitial ad did show.
    }

    override fun onAdDismissedFullScreenContent() {
      // Interstitial ad did dismiss.
      interstitialAd = null
    }

    override fun onAdFailedToShowFullScreenContent(
      fullScreenContentError: FullScreenContentError
    ) {
      // Interstitial ad failed to show.
      Log.e(TAG, "Interstitial ad failed to show: ${fullScreenContentError.message}")
    }

    override fun onAdImpression() {
      // Interstitial ad did record an impression.
    }

    override fun onAdClicked() {
      // Interstitial ad did record a click.
    }
  }

Java

// Listen for ad events.
if (interstitialAd == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.");
  return;
}

interstitialAd.setAdEventCallback(
    new InterstitialAdEventCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Interstitial ad did show.
      }

      @Override
      public void onAdDismissedFullScreenContent() {
        // Interstitial ad did dismiss.
        interstitialAd = null;
      }

      @Override
      public void onAdFailedToShowFullScreenContent(
          @NonNull FullScreenContentError fullScreenContentError) {
        // Interstitial ad failed to show.
        Log.e(TAG, "Interstitial ad failed to show: " + fullScreenContentError.getMessage());
      }

      @Override
      public void onAdImpression() {
        // Interstitial ad did record an impression.
      }

      @Override
      public void onAdClicked() {
        // Interstitial ad did record a click.
      }
    });

Optional: Listen to preloading events

When you start preloading ads, register for preload events to get notified when ads are preloaded successfully, fail to preload, or the ad cache is exhausted.

The following example shows how to register for preloading ad events:

Kotlin

val preloadCallback =
  // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(
        TAG,
        ("Interstitial preload ad $preloadId failed to load with error: ${adError.message}"),
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Interstitial preload ad $preloadId is not available")
      // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
    }

    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
      Log.i(TAG, "Interstitial preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

Java

PreloadCallback preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Interstitial preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
        // [Optional] Get the error response info for additional details.
        // ResponseInfo responseInfo = adError.getResponseInfo();
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        Log.i(TAG, "Interstitial preload ad " + preloadId + " is not available");
        // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, "Interstitial preload ad " + preloadId + " is available");
      }
    };

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

When an ad fails to load, GMA Next-Gen SDK automatically preloads ads and retries failed requests for preloaded configurations.

Optional: Check for ad availability

If you need to know whether an ad is available, check for ad availability. The following example shows how to check whether a preloaded ad is available:

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return InterstitialAdPreloader.isAdAvailable(adUnitId)
}

Java

private boolean isAdAvailable(String adUnitId) {
  return InterstitialAdPreloader.isAdAvailable(adUnitId);
}

Optional: Set the buffer size

The buffer size controls the number of preloaded ads held in memory. By default, Google optimizes buffer size to balance memory consumption and ad serving latency. You can set a custom buffer size to increase the number of ads kept in memory. We recommend a maximum buffer size of four.

The following example shows how to set a buffer size of four preloaded ads:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Maintain small or default buffer size unless rapid transitions are expected.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
InterstitialAdPreloader.start(adUnitId, preloadConfig)

Java

// Maintain small or default buffer size unless rapid transitions are expected.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
InterstitialAdPreloader.start(adUnitId, preloadConfig);

Preload cache limits

GMA Next-Gen SDK enforces an app-wide limit on the total number of preloaded ads across all ad units and preload IDs:

  • Default limit: Google holds a maximum of 6 preloaded ads in memory. This limit is shared across all formats and preload IDs.
  • We recommend to keep a buffer size of 2 or 3 per preload ID.

Optional: Stop preloading ads

If you don't need to show ads for a specific preload ID again in the session, you can stop preloading ads. To stop loading ads for a specific preload ID, call the destroy() method with a preload ID. Calling the destroy() method removes all preloaded ads associated with the preload ID from the cache.

The following example shows how to stop preloading ads:

Kotlin

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  InterstitialAdPreloader.destroy(adUnitId)
}

Java

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  InterstitialAdPreloader.destroy(adUnitId);
}

Optional: Read the response info

Read the next preloaded ad's response info without removing the ad from the cache.

The following example shows how to read the next preloaded ad response info:

Kotlin

val responseInfo = InterstitialAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

Java

ResponseInfo responseInfo = InterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());