Ad preloading (Alpha)

  • Ad preloading is an SDK-managed process for loading and caching ads, eliminating the need for manual ad loading.

  • Ad preloading is currently available for interstitial, rewarded, and app open ad formats.

  • To start preloading ads, call the start() method with a PreloadConfiguration.

  • Implement PreloadCallbackV2 to receive notifications about ad preloading events.

  • To get and show a preloaded ad, use the pollAd() method and then call the show() method on the retrieved ad object.
Select platform: Android (beta) New Android iOS Unity

Ad preloading is a Google-managed ad loading feature in Google Mobile Ads SDK that manages ad loading and caching on your behalf. Ad preloading requires a change in how you manage ad loading. To optimize performance using ad preloading, disable custom caching and delegate that responsibility to Google Mobile Ads SDK.

Ad preloading offers the following benefits over manual ad loading:

  • Reference management: holds loaded ads so you don't have to maintain references until you're ready to show them.
  • Automatic reloading: automatically loads a new ad when you pull one out of the cache.
  • Managed retries: automatically retries failed requests using exponential backoff.
  • Expiration handling: automatically refreshes ads before they expire (typically after one hour).
  • Cache optimization: If you use a cache size larger than one, Google Mobile Ads SDK optimizes the cache order to deliver the best ad.

This guide covers configuring preload ads, checking preload ad availability, and showing the preloaded ad.

Prerequisites

Before you proceed with the tutorial, you need to complete the following items:

  • Install Google Mobile Ads SDK version 24.4.0 or higher. Developer resources for earlier versions are available at 23.6.1 - 24.3.0, but we recommend using 24.4.0 or higher and following this guide going forward.
  • Set up Google Mobile Ads SDK.
  • Optional: Download and run the example app in Java or Kotlin.

Start preloading ads

To begin preloading ads, call start(). Call this method only once at the start of the app. After you call start(), Google Mobile Ads SDK automatically preloads ads and retries failed requests for preloaded configurations.

The following example starts preloading ads:

Kotlin

// Define a PreloadConfiguration.
val configuration = PreloadConfiguration.Builder("AD_UNIT_ID").build()
// Start the preloading with a given preload ID, preload configuration.
InterstitialAdPreloader.start("AD_UNIT_ID", configuration)
InterstitialAdPreloaderSnippets.kt

Java

// Define a PreloadConfiguration.
PreloadConfiguration configuration = new PreloadConfiguration.Builder("AD_UNIT_ID").build();
// Start the preloading with a given preload ID, preload configuration.
InterstitialAdPreloader.start("AD_UNIT_ID", configuration);
InterstitialAdPreloaderSnippets.java

Replace AD_UNIT_ID with your ad unit ID.

Get and show the preloaded ad

When using ad preloading, Google Mobile Ads SDK holds cached ads. When you want to show an ad, call pollAd(). Google Mobile Ads SDK retrieves the available ad and automatically preloads the next ad in the background.

Avoid calling this method until you are ready to show an ad. Keeping ads in the cache lets Google Mobile Ads SDK automatically refresh expired ads and perform cache optimization.

The following example retrieves and shows a preloaded ad:

Kotlin

// pollAd() returns the next available ad and loads another ad in the background.
val ad = InterstitialAdPreloader.pollAd("AD_UNIT_ID")

// [Optional] Interact with the ad as needed.
ad?.onPaidEventListener = OnPaidEventListener {
  // [Optional] Send the impression-level ad revenue information to your preferred
  // analytics server directly within this callback.
}

// Show the ad immediately.
ad?.show(activity)
InterstitialAdPreloaderSnippets.kt

Java

// pollAd() returns the next available ad and loads another ad in the background.
InterstitialAd ad = InterstitialAdPreloader.pollAd("AD_UNIT_ID");

if (ad != null) {
  // [Optional] Interact with the ad object as needed.
  ad.setOnPaidEventListener(
      adValue -> {
        // [Optional] Send the impression-level ad revenue information to your preferred
        // analytics server directly within this callback.
      });

  // Show the ad immediately.
  ad.show(activity);
}
InterstitialAdPreloaderSnippets.java

Check preloading ad availability

To check for ad availability, choose one of the following:

Get preloaded ad availability

The following example checks for ad availability:

Kotlin

// Verify that a preloaded ad is available.
if (!InterstitialAdPreloader.isAdAvailable("AD_UNIT_ID")) {
  // No ads are available to show.
}
InterstitialAdPreloaderSnippets.kt

Java

// Verify that a preloaded ad is available.
if (!InterstitialAdPreloader.isAdAvailable("AD_UNIT_ID")) {
  // No ads are available to show.
}
InterstitialAdPreloaderSnippets.java

Listen to preloaded ad availability

Register for preload events to get notified when ads are preloaded successfully, fail to preload, or the ad cache is exhausted.

Preload events are intended for analytics purposes. Within preload event callbacks:

  • Don't call start().
  • Avoid calling pollAd() unless the ad will be shown immediately.

The following example registers for ad events:

Kotlin

// Define a callback to receive preload events.
val callback =
  object : PreloadCallbackV2() {
    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo?) {
      // Called when preloaded ads are available.
    }

    override fun onAdsExhausted(preloadId: String) {
      // Called when no preloaded ads are available.
    }

    override fun onAdFailedToPreload(preloadId: String, adError: AdError) {
      // Called when preloaded ads failed to load.
    }
  }
InterstitialAdPreloaderSnippets.kt

Java

// Define a callback to receive preload events.
PreloadCallbackV2 callback =
    new PreloadCallbackV2() {
      @Override
      public void onAdPreloaded(
          @NonNull String preloadId, @Nullable ResponseInfo responseInfo) {
        // Called when preloaded ads are available.
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        // Called when no preloaded ads are available.
      }

      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull AdError adError) {
        // Called when preloaded ads failed to load.
      }
    };
InterstitialAdPreloaderSnippets.java

Stop preloading ads

If you don't need to show ads for a preload ID again in the session, you can stop preloading ads. To stop preloading ads for a specific preload ID, call destroy() with a preload ID.

Kotlin

// Stops the preloading and destroy preloaded ads.
InterstitialAdPreloader.destroy("AD_UNIT_ID")
// Stops the preloading and destroy all ads.
InterstitialAdPreloader.destroyAll()
InterstitialAdPreloaderSnippets.kt

Java

// Stops the preloading and destroy preloaded ads.
InterstitialAdPreloader.destroy("AD_UNIT_ID");
// Stops the preloading and destroy all ads.
InterstitialAdPreloader.destroyAll();
InterstitialAdPreloaderSnippets.java

Set the buffer size

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. If your app displays ads before the next ad is loaded, you can set a custom buffer size to increase the number of ads kept in memory. We recommend a buffer size of at most four.

Kotlin

// Define a PreloadConfiguration and buffer up to 5 preloaded ads.
val configuration = PreloadConfiguration.Builder("AD_UNIT_ID").setBufferSize(5).build()
InterstitialAdPreloaderSnippets.kt

Java

// Define a PreloadConfiguration and buffer up to 5 preloaded ads.
PreloadConfiguration configuration =
    new PreloadConfiguration.Builder("AD_UNIT_ID").setBufferSize(5).build();
InterstitialAdPreloaderSnippets.java