广告预加载功能可在 GMA Next-Gen SDK 中自动加载、缓存和重新加载广告。 如果您使用的是单次加载,请迁移到广告预加载,以实现自动化生命周期管理、代管式重试和优化广告选择。如需详细了解广告预加载的概念,请参阅广告预加载。广告预加载支持开屏广告、插页式广告、激励广告和插页式激励广告格式。
本页面将引导您将现有的单次加载广告实现迁移到广告预加载。本指南以插页式广告为例,但您可以将相同的流程应用于支持的广告格式。
前提条件
在继续操作之前,请完成以下步骤:
- 设置 GMA Next-Gen SDK。
- 已采用单次加载广告植入方式。
- 启用测试广告,以使用测试广告单元验证您的植入。
通过广告预加载功能请求广告
在单次加载模式下,您需要为每个广告请求单独请求一个广告。借助广告预加载功能,您只需使用预加载 ID 和预加载配置启动一次预加载器。
以下示例比较了单次加载和广告预加载的广告请求:
Kotlin
单次加载:
// Request a single ad. val adRequest = AdRequest.Builder(adUnitId).build() InterstitialAd.load(adRequest, adLoadCallback)
广告预加载:
// Start the preloader once with a preload configuration. val adRequest = AdRequest.Builder(adUnitId).build() val preloadConfig = PreloadConfiguration(adRequest) InterstitialAdPreloader.start(adUnitId, preloadConfig)
Java
单次加载:
// Request a single ad. AdRequest adRequest = new AdRequest.Builder(adUnitId).build(); InterstitialAd.load(adRequest, adLoadCallback);
广告预加载:
// Start the preloader once with a preload configuration. AdRequest adRequest = new AdRequest.Builder(adUnitId).build(); PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest); InterstitialAdPreloader.start(adUnitId, preloadConfig);
切换到预加载回调
在单次加载中,您需要为每个单独的广告请求附加一个加载回调。借助广告预加载功能,您可以注册回调监听器来观察预加载器缓存更新。当广告完成预加载、加载失败或缓存用尽时,这些回调会通知您的应用。
以下示例比较了如何为单次加载和广告预加载注册预加载回调:
Kotlin
单次加载:
// Listen for single ad request load results. val adLoadCallback = object : AdLoadCallback<InterstitialAd> { override fun onAdLoaded(ad: InterstitialAd) { // Ad loaded for a single request. } override fun onAdFailedToLoad(adError: LoadAdError) { Log.d(TAG, "Ad failed to load: ${adError.message}") } } InterstitialAd.load(adRequest, adLoadCallback)
广告预加载:
// Observe cache updates across multiple ads. val preloadCallback = object : PreloadCallback { override fun onAdPreloaded( preloadId: String, responseInfo: ResponseInfo, ) { // Ad preloaded into the cache and is ready to show. } override fun onAdFailedToPreload( preloadId: String, adError: LoadAdError, ) { Log.d(TAG, "Ad failed to preload: ${adError.message}") } override fun onAdsExhausted(preloadId: String) { // All preloaded ads in the cache have been shown. Log.d(TAG, "Ads exhausted for: $preloadId") } } InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)
Java
单次加载:
// Listen for single ad request load results. AdLoadCallback<InterstitialAd> adLoadCallback = new AdLoadCallback<InterstitialAd>() { @Override public void onAdLoaded(@NonNull InterstitialAd ad) { // Ad loaded for a single request. } @Override public void onAdFailedToLoad(@NonNull LoadAdError adError) { Log.d(TAG, "Ad failed to load: " + adError.getMessage()); } }; InterstitialAd.load(adRequest, adLoadCallback);
广告预加载:
// Observe cache updates across multiple ads. PreloadCallback preloadCallback = new PreloadCallback() { @Override public void onAdPreloaded( @NonNull String preloadId, @NonNull ResponseInfo responseInfo) { // Ad preloaded into the cache and is ready to show. } @Override public void onAdFailedToPreload( @NonNull String preloadId, @NonNull LoadAdError adError) { Log.d(TAG, "Ad failed to preload: " + adError.getMessage()); } @Override public void onAdsExhausted(@NonNull String preloadId) { // All preloaded ads in the cache have been shown. Log.d(TAG, "Ads exhausted for: " + preloadId); } }; InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);
当 GMA Next-Gen SDK 加载或缓存广告时,或者当您的应用展示广告时,预加载器会调用回调方法。
展示缓存中的广告
在单次加载中,您将加载的广告保存在变量中,并在广告可用时展示。借助广告预加载功能,当有广告可供展示时,您可以直接从缓存中检索广告。在这两种方法中,请在展示广告之前将事件监听器附加到广告。
以下示例比较了使用广告预加载和单次加载展示广告的效果:
Kotlin
单次加载:
// Retrieve the ad from a saved variable. val interstitialAd = this.interstitialAd ?: return // Display the ad. interstitialAd.show(activity)
广告预加载:
// Retrieve the ad directly from the preloader cache. val interstitialAd = InterstitialAdPreloader.pollAd(adUnitId) ?: return // Display the ad. interstitialAd.show(activity)
Java
单次加载:
// Retrieve the ad from a saved variable. InterstitialAd interstitialAd = this.interstitialAd; if (interstitialAd == null) { return; } // Display the ad. interstitialAd.show(activity);
广告预加载:
// Retrieve the ad directly from the preloader cache. InterstitialAd interstitialAd = InterstitialAdPreloader.pollAd(adUnitId); if (interstitialAd == null) { return; } // Display the ad. interstitialAd.show(activity);
移除手动缓存和重新加载
当您获取广告时,预加载器会自动加载替代广告。与单次加载不同,您无需手动存储广告引用或编写重新加载逻辑。
从代码中移除以下模式:
- 成员变量缓存:删除存储广告对象的成员变量。
- 手动重新加载:在用户关闭广告或广告未能展示后,删除加载调用。
- 自定义重试定时器:删除重试处理程序、退避循环和定时器。GMA Next-Gen SDK 会自动重试失败的预加载请求。
比较已完成示例
以下示例比较了迁移到广告预加载之前和之后的完整插页式广告植入:
Kotlin
单次加载:
// 1. Maintain a member variable to store the ad. private var interstitialAd: InterstitialAd? = null // 2. Load the ad and listen for load completion. private fun loadAd() { val adRequest = AdRequest.Builder(adUnitId).build() InterstitialAd.load( adRequest, object : AdLoadCallback<InterstitialAd> { override fun onAdLoaded(ad: InterstitialAd) { interstitialAd = ad } override fun onAdFailedToLoad(adError: LoadAdError) { interstitialAd = null } }, ) } // 3. Show the saved ad. private fun showAd(activity: Activity) { val interstitialAd = this.interstitialAd ?: return interstitialAd.adEventCallback = object : InterstitialAdEventCallback { override fun onAdDismissedFullScreenContent() { // Reload the ad after dismissal in single-load integrations. loadAd() } override fun onAdFailedToShowFullScreenContent( fullScreenContentError: FullScreenContentError, ) { Log.d(TAG, "Ad failed to show: ${fullScreenContentError.message}") } } interstitialAd.show(activity) }
广告预加载:
// 1. Start preloading with a callback to listen for loaded ads. private fun startPreloading(adUnitId: String) { val preloadCallback = object : PreloadCallback { override fun onAdPreloaded( preloadId: String, responseInfo: ResponseInfo, ) { // Ad preloaded successfully. } override fun onAdFailedToPreload( preloadId: String, adError: LoadAdError, ) { Log.d(TAG, "Ad failed to preload: ${adError.message}") } } val adRequest = AdRequest.Builder(adUnitId).build() val preloadConfig = PreloadConfiguration(adRequest) InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback) } // 2. Show the ad immediately after polling. private fun showAd(activity: Activity, adUnitId: String) { val interstitialAd = InterstitialAdPreloader.pollAd(adUnitId) ?: return interstitialAd.adEventCallback = object : InterstitialAdEventCallback { override fun onAdDismissedFullScreenContent() { // Preloading automatically fetches a replacement ad. } override fun onAdFailedToShowFullScreenContent( fullScreenContentError: FullScreenContentError, ) { Log.d(TAG, "Ad failed to show: ${fullScreenContentError.message}") } } interstitialAd.show(activity) }
Java
单次加载:
// 1. Maintain a member variable to store the ad. private InterstitialAd interstitialAd; // 2. Load the ad and listen for load completion. private void loadAd() { AdRequest adRequest = new AdRequest.Builder(adUnitId).build(); InterstitialAd.load( adRequest, new AdLoadCallback<InterstitialAd>() { @Override public void onAdLoaded(@NonNull InterstitialAd ad) { interstitialAd = ad; } @Override public void onAdFailedToLoad(@NonNull LoadAdError adError) { interstitialAd = null; } }); } // 3. Show the saved ad. private void showAd(Activity activity) { if (interstitialAd == null) { return; } interstitialAd.setAdEventCallback( new InterstitialAdEventCallback() { @Override public void onAdDismissedFullScreenContent() { // Reload the ad after dismissal in single-load integrations. loadAd(); } @Override public void onAdFailedToShowFullScreenContent( @NonNull FullScreenContentError fullScreenContentError) { Log.d( TAG, "Ad failed to show: " + fullScreenContentError.getMessage()); } }); interstitialAd.show(activity); }
广告预加载:
// 1. Start preloading with a callback to listen for loaded ads. private void startPreloading(String adUnitId) { PreloadCallback preloadCallback = new PreloadCallback() { @Override public void onAdPreloaded( @NonNull String preloadId, @NonNull ResponseInfo responseInfo) { // Ad preloaded successfully. } @Override public void onAdFailedToPreload( @NonNull String preloadId, @NonNull LoadAdError adError) { Log.d(TAG, "Ad failed to preload: " + adError.getMessage()); } }; AdRequest adRequest = new AdRequest.Builder(adUnitId).build(); PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest); InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback); } // 2. Show the ad immediately after polling. private void showAd(Activity activity, String adUnitId) { InterstitialAd interstitialAd = InterstitialAdPreloader.pollAd(adUnitId); if (interstitialAd == null) { return; } interstitialAd.setAdEventCallback( new InterstitialAdEventCallback() { @Override public void onAdDismissedFullScreenContent() { // Preloading automatically fetches a replacement ad. } @Override public void onAdFailedToShowFullScreenContent( @NonNull FullScreenContentError fullScreenContentError) { Log.d( TAG, "Ad failed to show: " + fullScreenContentError.getMessage()); } }); interstitialAd.show(activity); }
后续步骤
探索以下资源,了解如何配置预加载功能、集成广告格式以及测试您的实现: