欢迎在 Google 广告和效果衡量社区服务器的 #gma-next-gen-sdk Discord 频道中分享您对 GMA 新一代 SDK 的反馈。

广告预加载（Alpha 版）

广告预加载是 GMA Next-Gen SDK 中的一项 Google 管理的广告加载功能，它可代表您管理广告加载和缓存。广告预加载需要您更改管理广告加载的方式。如需使用广告预加载优化性能，请停用自定义缓存并将该责任委托给 GMA Next-Gen SDK。

与手动广告加载相比，广告预加载具有以下优势：

引用管理：缓存已加载的广告，因此您无需维护引用，直到准备好展示广告为止。
自动重新加载：当您从缓存中拉取广告时，会自动加载新广告。
托管重试：使用指数退避算法自动重试失败的请求。
到期处理：在广告到期（通常为一小时后）之前自动刷新广告。
缓存优化：如果您使用的缓存大小大于 1，GMA Next-Gen SDK 会优化缓存顺序，以投放最佳广告。

本指南介绍了如何配置预加载广告、检查预加载广告的可用性以及展示预加载的广告。

前提条件

在继续学习本教程之前，您需要完成以下事项：

安装 GMA Next-Gen SDK 0.14.0-alpha01 或更高版本。
设置 GMA Next-Gen SDK。

可选：下载并运行示例应用。

开始预加载广告

如需开始预加载广告，请调用 startPreload()。请仅在应用启动时调用此方法一次。调用 startPreload()后，GMA Next-Gen SDK会自动预加载广告，并重试预加载配置的失败请求。

以下示例开始预加载广告：

Kotlin

private fun startPreloading(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}
InterstitialAdSnippets.kt

Java

private void startPreloading(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}
InterstitialAdSnippets.java

获取并展示预加载的广告

使用广告预加载时，GMA Next-Gen SDK 会缓存广告。当您想要展示广告时，请调用 pollAd()。GMA Next-Gen SDK 会检索可用的广告，并在后台自动预加载下一个广告。

在准备好展示广告之前，请避免调用此方法。将广告保留在缓存中可让 GMA Next-Gen SDK 自动刷新已过期的广告并执行缓存优化。

以下示例检索并展示了预加载的广告：

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)
  }
}
InterstitialAdSnippets.kt

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);
  }
}
InterstitialAdSnippets.java

检查预加载广告的可用性

如需检查广告的可用性，请选择以下选项之一：

获取预加载广告的可用性
监听预加载广告的可用性

获取预加载广告的可用性

以下示例检查了广告的可用性：

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return InterstitialAdPreloader.isAdAvailable(adUnitId)
}
InterstitialAdSnippets.kt

Java

private boolean isAdAvailable(String adUnitId) {
  return InterstitialAdPreloader.isAdAvailable(adUnitId);
}InterstitialAdSnippets.java

监听预加载广告的可用性

注册预加载事件，以便在广告预加载成功、预加载失败或广告缓存耗尽时收到通知。

预加载事件旨在用于分析。在预加载事件回调中：

请勿调用 startPreload()。
除非广告会立即展示，否则请避免调用 pollAd()。

以下示例注册了广告事件：

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)
}
InterstitialAdSnippets.kt

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);
}
InterstitialAdSnippets.java

停止预加载广告

如果您在会话中不需要再次展示具有预加载 ID 的广告，则可以停止预加载广告。如需停止预加载具有特定预加载 ID 的广告，请使用预加载 ID 调用 destroy()。

设置缓冲区大小

缓冲区空间控制着内存中缓存的预加载广告数量。默认情况下，Google 会优化缓冲区空间大小，以平衡内存消耗和广告投放延迟。如果您的应用在加载下一个广告之前展示广告，您可以设置自定义缓冲区空间，以增加内存中保留的广告数量。我们建议缓冲区大小最多为 4。

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 3)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}
InterstitialAdSnippets.kt

Java

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 3);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}
InterstitialAdSnippets.java

广告预加载（Alpha 版） 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

前提条件

开始预加载广告

Kotlin

Java

获取并展示预加载的广告

Kotlin

Java

检查预加载广告的可用性

获取预加载广告的可用性

Kotlin

Java

监听预加载广告的可用性

Kotlin

Java

停止预加载广告

设置缓冲区大小

Kotlin

Java

广告预加载（Alpha 版）