Ad preloading (beta)

Page Summary

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

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

• To start preloading ads, call the preload() method; the SDK will automatically retry failed ad requests for preloaded configurations.

• You can optionally modify, stop, and set the buffer size for preloaded ads.

• You can receive notifications for ad preloading events by implementing GADPreloadDelegate.

• To get and show a preloaded ad, ensure an ad is available using isAdAvailableWithPreloadID and then call the appropriate method to retrieve and present the ad.

• You can check the availability of preloaded ads using the isAdAvailableWithPreloadID method.

Select platform: iOS Unity Android (Legacy)

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

Start preloading ads

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

The following example starts preloading ads:

Swift

private func startPreloading(adUnitID: String) {
  // Start the preloading initialization process.
  let request = Request()
  let interstitialConfig = PreloadConfigurationV2(
    adUnitID: adUnitID, request: request)
  InterstitialAdPreloader.shared.preload(
    for: adUnitID, configuration: interstitialConfig, delegate: self)
}
AdPreloaderSnippets.swift

Objective-C

- (void)startPreloadingWithAdUnitID:(nonnull NSString *)adUnitID {
  // Start the preloading initialization process.
  GADRequest *request = [GADRequest request];
  GADPreloadConfigurationV2 *interstitialConfig =
      [[GADPreloadConfigurationV2 alloc] initWithAdUnitID:adUnitID
                                                  request:request];

  [GADInterstitialAdPreloader.sharedInstance preloadForPreloadID:adUnitID
                                                   configuration:interstitialConfig
                                                        delegate:self];
}
AdPreloaderSnippets.m

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 the adWithPreloadID method. Google Mobile Ads SDK retrieves an available ad and automatically preloads the next ad in the background.

Avoid calling the adWithPreloadID method until you're 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:

Swift

private func showInterstitialAd(adUnitID: String) {
  // Verify that the preloaded ad is available before polling.
  guard isInterstitialAvailable(adUnitID: adUnitID) else {
    print("Preloaded interstitial ad is not available.")
    return
  }

  // Polling returns the next available ad and loads another ad in the background.
  let ad = InterstitialAdPreloader.shared.ad(with: adUnitID)

  // Interact with the ad object as needed.
  print("Interstitial ad response info: \(String(describing: ad?.responseInfo))")
  ad?.paidEventHandler = { (value: AdValue) in
    print("Interstitial ad paid event: \(value.value), \(value.currencyCode)")
  }

  ad?.fullScreenContentDelegate = self
  ad?.present(from: self)
}
AdPreloaderSnippets.swift

Objective-C

- (void)showInterstitialAdWithAdUnitID:(nonnull NSString *)adUnitID {
  // Verify that the preloaded ad is available before polling.
  if (![self isInterstitialAvailableWithAdUnitID:adUnitID]) {
    NSLog(@"Preloaded interstitial ad is not available.");
    return;
  }

  // Getting the preloaded ad loads another ad in the background.
  GADInterstitialAd *ad =
      [GADInterstitialAdPreloader.sharedInstance adWithPreloadID:adUnitID];

  // Interact with the ad object as needed.
  NSLog(@"Interstitial ad response info: %@", ad.responseInfo);
  ad.paidEventHandler = ^(GADAdValue *_Nonnull value) {
    NSLog(@"Interstitial ad paid event: %@ %@ ", value.value, value.currencyCode);
  };
  ad.fullScreenContentDelegate = self;
  [ad presentFromRootViewController:self];
}
AdPreloaderSnippets.m

Get preloaded ad metadata

To get preloaded ad metadata, you can look up the ad's response info object. This process lets you inspect the ad's metadata without removing it from the cache.

The following example looks up a preloaded ad's metadata from the response info object:

Swift

private func getInterstitialAdResponseInfo(preloadID: String) {
  // Get the response info for the preloaded ad.
  if let responseInfo = InterstitialAdPreloader.shared.responseInfo(
    with: preloadID)
  {
    print("Ad response ID: \(responseInfo.responseIdentifier ?? "")")
  }
}
AdPreloaderSnippets.swift

Objective-C

- (void)getInterstitialAdResponseInfoWithPreloadID:(nonnull NSString *)preloadID {
  // Get the response info for the preloaded ad.
  GADResponseInfo *responseInfo =
      [GADInterstitialAdPreloader.sharedInstance
          adResponseInfoWithPreloadID:preloadID];
  if (responseInfo) {
    NSLog(@"Ad response ID: %@", responseInfo.responseIdentifier);
  }
}
AdPreloaderSnippets.m

Check preloading ad availability

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

• Get preload ad availability
• Listen to preload ad availability

Get preloaded ad availability

The following example checks for ad availability:

Swift

private func isInterstitialAvailable(adUnitID: String) -> Bool {
  // Verify that an ad is available before polling.
  return InterstitialAdPreloader.shared.isAdAvailable(with: adUnitID)
}
AdPreloaderSnippets.swift

Objective-C

- (BOOL)isInterstitialAvailableWithAdUnitID:(nonnull NSString *)adUnitID {
  // Verify that an ad is available before polling.
  return [GADInterstitialAdPreloader.sharedInstance isAdAvailableWithPreloadID:adUnitID];
}
AdPreloaderSnippets.m

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 adWithPreloadID unless the ad will be shown immediately.

The following example registers for ad events:

Swift

func adAvailable(forPreloadID preloadID: String, responseInfo: ResponseInfo) {
  // This callback indicates that an ad is available for the specified configuration.
  // No action is required here, but updating the UI can be useful in some cases.
  print("Ad preloaded successfully for ad preload ID: \(preloadID)")
}

func adsExhausted(forPreloadID preloadID: String) {
  // This callback indicates that all the ads for the specified configuration have been
  // consumed and no ads are available to show. No action is required here, but updating
  // the UI can be useful in some cases.
  // Don't call InterstitialAdPreloader.shared.preload or
  // InterstitialAdPreloader.shared.ad from adsExhausted.
  print("Ad exhausted for ad preload ID: \(preloadID)")
}

func adFailedToPreload(forPreloadID preloadID: String, error: Error) {
  print(
    "Ad failed to load with ad preload ID: \(preloadID), Error: \(error.localizedDescription)"
  )
}
AdPreloaderSnippets.swift

Objective-C

- (void)adAvailableForPreloadID:(nonnull NSString *)preloadID
                   responseInfo:(nonnull GADResponseInfo *)responseInfo {
  // This callback indicates that an ad is available for the specified configuration.
  // No action is required here, but updating the UI can be useful in some cases.
  NSLog(@"Ad preloaded successfully for ad unit ID: %@", preloadID);
}

- (void)adsExhaustedForPreloadID:(nonnull NSString *)preloadID {
  // This callback indicates that all the ads for the specified configuration have been
  // consumed and no ads are available to show. No action is required here, but updating
  // the UI can be useful in some cases.
  // Don't call [GAD<Format>AdPreloader preloadForPreloadID:] or
  // [GAD<Format>AdPreloader adWithPreloadID:] from adsExhaustedForPreloadID.
  NSLog(@"Ad exhausted for ad preload ID: %@", preloadID);
}

- (void)adFailedToPreloadForPreloadID:(nonnull NSString *)preloadID
                                error:(nonnull NSError *)error {
  NSLog(@"Ad failed to load with ad preload ID: %@, Error: %@", preloadID,
        error.localizedDescription);
}
AdPreloaderSnippets.m

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 stopPreloadingAndRemoveAdsForPreloadID with a preload ID. To stop preloading for all preloaders, call stopPreloadingAndRemoveAllAds.

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.

Swift

let preloadConfig = PreloadConfigurationV2(adUnitID: "ca-app-pub-3940256099942544/1712485313")
preloadConfig.bufferSize = 3

Objective-C

GADPreloadConfigurationV2 *preloadConfig =
    [[GADPreloadConfigurationV2 alloc] initWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"];
preloadConfig.bufferSize = 3;

Preload cache limits

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

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

Note: If your app can benefit from an increased app-wide limit, contact your account manager to request an increase.