Ad preloading (Alpha)

  • Ad preloading is an SDK-managed process that automatically loads and caches ads, eliminating manual loading and handling of callbacks.

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

  • You can start preloading ads by calling Preload() and optionally modify or stop preloading using Destroy() or DestroyAll().

  • The number of preloaded ads held in memory can be controlled with the buffer size setting.

  • You can receive notifications for ad preloading events by implementing Action<>.
Select platform: Android (beta) New Android iOS Unity

Ad preloading is a Google-managed ad loading feature in Google Mobile Ads Unity Plugin 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 Unity Plugin.

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 Unity Plugin 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:

Start preloading ads

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

The following example starts preloading ads:

var preloadConfiguration = new PreloadConfiguration
{
    AdUnitId = AD_UNIT_ID,
    Request = new AdRequest(),
};

// Start the preloading initialization process after MobileAds.Initialize().
InterstitialAdPreloader.Preload(
    // The Preload ID can be any unique string to identify this configuration.
    AD_UNIT_ID,
    preloadConfiguration);

Get and show the preloaded ad

When using ad preloading, Google Mobile Ads Unity Plugin holds cached ads. When you want to show an ad, call DequeueAd(). Google Mobile Ads Unity Plugin 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 Unity Plugin automatically refresh expired ads and perform cache optimization.

The following example retrieves and shows a preloaded ad:

// DequeueAd returns the next available ad and loads another ad in the background.
var ad = InterstitialAdPreloader.DequeueAd(AD_UNIT_ID);

if (ad != null)
{
    // [Optional] Interact with the ad object as needed.
    ad.OnAdPaid += (AdValue value) =>
    {
        Debug.Log($"Ad paid: {value.CurrencyCode} {value.Value}");
        // [Optional] Send the impression-level ad revenue information to your preferred
        // analytics server directly within this callback.
    };

    // Do not hold onto preloaded ads, always show a preloaded ad immediately.
    ad.Show();
}

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:

var isAdAvailable = InterstitialAdPreloader.IsAdAvailable(AD_UNIT_ID);

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 Preload().
  • Avoid calling DequeueAd() unless the ad will be shown immediately.

The following example registers for ad events:


void StartPreloadWithCallbacks()
{
    var preloadConfiguration = new PreloadConfiguration
    {
        AdUnitId = AD_UNIT_ID,
        Request = new AdRequest(),
    };

    // Start the preloading initialization process after MobileAds.Initialize().
    InterstitialAdPreloader.Preload(
        // The Preload ID can be any unique string to identify this configuration.
        AD_UNIT_ID,
        preloadConfiguration,
        onAdPreloaded,
        onAdFailedToPreload,
        onAdsExhausted);
}

void onAdPreloaded(string preloadId, ResponseInfo responseInfo)
{
    Debug.Log($"Preload ad configuration {preloadId} was preloaded.");
}

void onAdFailedToPreload(string preloadId, AdError adError)
{
    string errorMessage = $"Preload ad configuration {preloadId} failed to " +
                          $"preload with error : {adError.GetMessage()}.";
    Debug.Log(errorMessage);
}

void onAdsExhausted(string preloadId)
{
    Debug.Log($"Preload ad configuration {preloadId} was exhausted");
    // [Important] Don't call Preload() or DequeueAd() from onAdsExhausted.
}

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.

InterstitialAdPreloader.Destroy(AD_UNIT_ID);
InterstitialAdPreloader.DestroyAll();

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.

new PreloadConfiguration
{
    AdUnitId = AD_UNIT_ID,
    Request = new AdRequest(),
    BufferSize = 5
};