Ad preloading (Alpha)

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.

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 the tutorial, you need to complete the following items:

Install Google Mobile Ads SDK version 12.6.0 or higher. Developer resources for earlier versions are available at 11.12.0 - 12.2.0, but we recommend using 12.6.0 or higher and following this guide going forward.
Set up Google Mobile Ads SDK.

Download and include the preloading preview headers into your project.
Optional: Download and run the ad preloading example app.

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 SDK automatically preloads ads and retries failed requests for preloaded configurations.

The following example starts preloading ads:

Swift

// Start the preloading initialization process.
let request = Request()
let interstitialConfig = PreloadConfigurationV2(
  adUnitID: Constants.interstitialAdUnitID, request: request)
InterstitialAdPreloader.shared.preload(
  for: Constants.interstitialAdUnitID, configuration: interstitialConfig, delegate: self)

Objective-C

// Start the preloading initialization process.
GADRequest *request = [GADRequest request];
GADPreloadConfigurationV2 *interstitialConfig = [[GADPreloadConfigurationV2 alloc] initWithAdUnitID:interstitialAdUnitID request:request];

[GADInterstitialAdPreloader.sharedInstance preloadForPreloadID:interstitialAdUnitID
                                                     configuration:interstitialConfig
                                                          delegate:self];

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 adWithPreloadID(). Google Mobile Ads SDK 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 SDK automatically refresh expired ads and perform cache optimization.

The following example retrieves and shows a preloaded ad:

Swift

private func showInterstitialAd() {
  // Verify that the preloaded ad is available before polling.
  guard isInterstitialAvailable() else {
    printAndShowAlert("Preload interstitial ad is exhausted.")
    return
  }

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

  // 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)
}

Objective-C

- (void)showInterstitialAd {
  // Verify that the preloaded ad is available before polling.
  if (![self isInterstitialAvailable]) {
    [self logAndShowAlert:@"Preloaded interstitial ad is not available."];
    return;
  }

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

  // 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];
}

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() -> Bool {
  // Verify that an ad is available before polling.
  return InterstitialAdPreloader.shared.isAdAvailable(with: Constants.interstitialAdUnitID)
}

Objective-C

- (BOOL)isInterstitialAvailable {
  // Verify that an ad is available before polling.
  return [GADInterstitialAdPreloader.sharedInstance isAdAvailableWithPreloadID:(interstitialAdUnitID)];
}

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.
  // [Important] Don't call AdPreloader.shared.preload or AdPreloader.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)"
  )
}

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.
  // [Important] 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);
}

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.

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.

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;

Ad preloading (Alpha) Stay organized with collections Save and categorize content based on your preferences.

Page Summary

Prerequisites

Start preloading ads

Swift

Objective-C

Get and show the preloaded ad

Swift

Objective-C

Check preloading ad availability

Get preloaded ad availability

Swift

Objective-C

Listen to preloaded ad availability

Swift

Objective-C

Stop preloading ads

Set the buffer size

Swift

Objective-C

Ad preloading (Alpha)