Ad preloading is a Google-managed ad loading feature in GMA Next-Gen 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 GMA Next-Gen 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, GMA Next-Gen 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 GMA Next-Gen SDK version 0.14.0-alpha01 or higher.
- Set up GMA Next-Gen SDK.
- Optional: Download and run the example app.
Start preloading ads
To begin preloading ads, call startPreload(). Call this method
only once at the start of the app. After you call
startPreload(), GMA Next-Gen SDK automatically
preloads ads and retries failed requests for preloaded configurations.
The following example starts preloading ads:
Kotlin
private fun startPreloading(adUnitId: String) {
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
InterstitialAdPreloader.start(adUnitId, preloadConfig)
}
Java
private void startPreloading(String adUnitId) {
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
InterstitialAdPreloader.start(adUnitId, preloadConfig);
}
Get and show the preloaded ad
When using ad preloading, GMA Next-Gen SDK holds cached ads.
When you want to show an ad, call pollAd().
GMA Next-Gen 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 GMA Next-Gen SDK automatically refresh expired ads and perform cache optimization.
The following example retrieves and shows a preloaded ad:
Kotlin
private fun pollAndShowAd(activity: Activity, adUnitId: String) {
// Polling returns the next available ad and loads another ad in the background.
val ad = InterstitialAdPreloader.pollAd(adUnitId)
// Interact with the ad object as needed.
ad?.apply {
Log.d(TAG, "Interstitial ad response info: ${this.getResponseInfo()}")
this.adEventCallback =
object : InterstitialAdEventCallback {
override fun onAdImpression() {
Log.d(TAG, "Interstitial ad recorded an impression.")
}
override fun onAdPaid(value: AdValue) {
Log.d(TAG, "Interstitial ad onPaidEvent: ${value.valueMicros} ${value.currencyCode}")
}
}
// Show the ad.
ad.show(activity)
}
}
Java
private void pollAndShowAd(Activity activity, String adUnitId) {
// Polling returns the next available ad and loads another ad in the background.
final InterstitialAd ad = InterstitialAdPreloader.pollAd(adUnitId);
// Interact with the ad object as needed.
if (ad != null) {
Log.d(TAG, "Interstitial ad response info: " + ad.getResponseInfo());
ad.setAdEventCallback(
new InterstitialAdEventCallback() {
@Override
public void onAdImpression() {
Log.d(TAG, "Interstitial ad recorded an impression.");
}
@Override
public void onAdPaid(AdValue value) {
Log.d(
TAG,
"Interstitial ad onPaidEvent: "
+ value.getValueMicros()
+ " "
+ value.getCurrencyCode());
}
});
// Show the ad.
ad.show(activity);
}
}
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:
Kotlin
private fun isAdAvailable(adUnitId: String): Boolean {
return InterstitialAdPreloader.isAdAvailable(adUnitId)
}
Java
private boolean isAdAvailable(String adUnitId) {
return InterstitialAdPreloader.isAdAvailable(adUnitId);
}
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
startPreload(). - Avoid calling
pollAd()unless the ad will be shown immediately.
The following example registers for ad events:
Kotlin
private fun startPreloadingWithCallback(adUnitId: String) {
val preloadCallback =
// [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
object : PreloadCallback {
override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
Log.i(
TAG,
("Interstitial preload ad $preloadId failed to load with error: ${adError.message}"),
)
// [Optional] Get the error response info for additional details.
// val responseInfo = adError.responseInfo
}
override fun onAdsExhausted(preloadId: String) {
Log.i(TAG, "Interstitial preload ad $preloadId is not available")
// [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
}
override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
Log.i(TAG, "Interstitial preload ad $preloadId is available")
}
}
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)
}
Java
private void startPreloadingWithCallback(String adUnitId) {
PreloadCallback preloadCallback =
// [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
new PreloadCallback() {
@Override
public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
Log.e(
TAG,
String.format(
"Interstitial preload ad %s failed to load with error: %s",
preloadId, adError.getMessage()));
// [Optional] Get the error response info for additional details.
// ResponseInfo responseInfo = adError.getResponseInfo();
}
@Override
public void onAdsExhausted(String preloadId) {
Log.i(TAG, "Interstitial preload ad " + preloadId + " is not available");
// [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
}
@Override
public void onAdPreloaded(String preloadId, ResponseInfo responseInfo) {
Log.i(TAG, "Interstitial preload ad " + preloadId + " is available");
}
};
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);
}
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.
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.
Kotlin
private fun setBufferSize(adUnitId: String) {
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 3)
InterstitialAdPreloader.start(adUnitId, preloadConfig)
}
Java
private void setBufferSize(String adUnitId) {
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 3);
InterstitialAdPreloader.start(adUnitId, preloadConfig);
}