<br />

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](https://developers.google.com/admob/flutter/quick-start.md.txt).

## 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:

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

Replace <var translate="no">_adUnitId</var> 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:

```dart
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 preload ad availability](https://developers.google.com/admob/flutter/ad-preloading.md.txt#get-preloaded-ad-availability)
- [Listen to preload ad availability](https://developers.google.com/admob/flutter/ad-preloading.md.txt#listen-preloaded-ad-availability)

### Get preloaded ad availability

The following example checks for ad availability:

```dart
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:

```dart
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`.

```dart
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.

```dart
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.

> [!NOTE]
> **Note:** If your app can benefit from an increased app-wide limit, contact your account manager to request an increase.