Ad preloading (beta)

  • Ad preloading is an SDK-managed process that automatically loads and caches interstitial, rewarded, and app open ad formats.

  • To start preloading ads, call Preload() after initializing the Mobile Ads SDK.

  • You can modify, stop, or set the buffer size for preloading ads.

  • Implement callbacks to receive notifications about ad preloading events.

  • Use DequeueAd() to get a preloaded ad and show it immediately.
Select platform: iOS Unity Android (Legacy)

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 this tutorial, you must set up Google Mobile Ads Unity Plugin.

Start preloading ads

When the app starts, call the Preload method once. After you call the Preload method, 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 the DequeueAd method. Google Mobile Ads Unity Plugin retrieves an available ad and automatically preloads the next ad in the background.

Avoid calling the DequeueAd method until you're 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. To stop preloading for all preloaders, call DestroyAll.

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.

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

Preload cache limits

Google Mobile Ads Unity Plugin enforces an app-wide limit on the total number of preloaded ads across all ad units and preload IDs:

  • Default limit: Google Mobile Ads Unity Plugin 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.