Ad preloading (Beta)

Select platform: iOS Unity Flutter Android (Legacy)

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

Start preloading ads

When the app starts, call the start method once. After you call the start method, Google Mobile Ads Flutter Plugin automatically preloads ads and retries failed requests for preloaded configurations.

The following example starts preloading ads:

InterstitialAdPreloader.start(
  preloadId: _adUnitId,
  preloadConfiguration: PreloadConfiguration(adUnitId: _adUnitId),
  callback: const PreloadCallback(),
);

Replace _adUnitId with your ad unit ID.

Get and show the preloaded ad

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

Avoid calling the pollAd method until you're ready to show an ad. Keeping ads in the cache lets Google Mobile Ads Flutter Plugin automatically refresh expired ads and perform cache optimization.

The following example retrieves and shows a preloaded ad:

void _pollAndShowAd() async {
  final InterstitialAd? ad = await InterstitialAdPreloader.pollAd(_adUnitId);
  if (ad != null) {
    _interstitialAd = ad;
    ad.fullScreenContentCallback = FullScreenContentCallback(
      onAdImpression: (ad) {
        // Called when an impression occurs on the ad.
        debugPrint('Ad recorded an impression.');
      },
    );
    ad.onPaidEvent = (ad, valueMicros, precision, currencyCode) {
      // Called when an ad is estimated to have earned money.
      debugPrint('Ad paid: $valueMicros $currencyCode.');
    };
    // Show the ad.
    await 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:

void _checkAdAvailability() async {
  final bool isAvailable = await InterstitialAdPreloader.isAdAvailable(
    _adUnitId,
  );
  debugPrint('Is ad available: $isAvailable');
}

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:

InterstitialAdPreloader.start(
  preloadId: _adUnitId,
  preloadConfiguration: PreloadConfiguration(adUnitId: _adUnitId),
  callback: PreloadCallback(
    onAdPreloaded: (preloadId, responseInfo) {
      debugPrint('Ad preloaded for ID: $preloadId');
    },
    onAdFailedToPreload: (preloadId, error) {
      debugPrint('Ad failed to preload for ID: $preloadId. Error: $error');
    },
    onAdsExhausted: (preloadId) {
      debugPrint('All preloaded ads exhausted for ID: $preloadId');
    },
  ),
);

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.

void _stopPreloading() async {
  await InterstitialAdPreloader.destroy(_adUnitId);
}

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.

InterstitialAdPreloader.start(
  preloadId: _adUnitId,
  preloadConfiguration: PreloadConfiguration(
    adUnitId: _adUnitId,
    bufferSize: 3,
  ),
  callback: const PreloadCallback(),
);

Preload cache limits

Google Mobile Ads Flutter 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 Flutter Plugin holds a maximum of 6 preloaded ads in memory. This limit is shared across all formats and preload IDs.
  • We recommend keeping a buffer size of two for each preload ID.