广告预加载（Beta 版）

选择平台： Android iOS Unity Android（旧版）

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

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

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

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

前提条件

在继续学习本教程之前，您必须先设置Google Mobile Ads SDK (Legacy)。

开始预加载广告

应用启动时，请调用 start 方法一次。调用 您调用 start 方法后，Google Mobile Ads SDK (Legacy) 会自动 预加载广告，并重试预加载配置的失败请求。

以下示例演示了如何开始预加载广告：

Kotlin

// Define a PreloadConfiguration.
val configuration = PreloadConfiguration.Builder("AD_UNIT_ID").build()
// Start the preloading with a given preload ID, preload configuration.
InterstitialAdPreloader.start("AD_UNIT_ID", configuration)
InterstitialAdPreloaderSnippets.kt

Java

// Define a PreloadConfiguration.
PreloadConfiguration configuration = new PreloadConfiguration.Builder("AD_UNIT_ID").build();
// Start the preloading with a given preload ID, preload configuration.
InterstitialAdPreloader.start("AD_UNIT_ID", configuration);
InterstitialAdPreloaderSnippets.java

将 AD_UNIT_ID 替换为您的广告单元 ID。

获取并展示预加载的广告

使用广告预加载时，Google Mobile Ads SDK (Legacy) 会存储缓存的广告。 当您想要展示广告时，请调用 pollAd 方法。 Google Mobile Ads SDK (Legacy) 会检索可用的广告，并在后台自动预加载 下一个广告。

在准备好展示广告之前，请避免调用 pollAd 方法。将广告保留在缓存中，可让 Google Mobile Ads SDK (Legacy) 自动刷新 已过期的广告并执行缓存优化。

以下示例演示了如何检索和展示预加载的广告：

Kotlin

// pollAd() returns the next available ad and loads another ad in the background.
val ad = InterstitialAdPreloader.pollAd("AD_UNIT_ID")

// [Optional] Interact with the ad as needed.
ad?.onPaidEventListener = OnPaidEventListener {
  // [Optional] Send the impression-level ad revenue information to your preferred
  // analytics server directly within this callback.
}

// Show the ad immediately.
ad?.show(activity)
InterstitialAdPreloaderSnippets.kt

Java

// pollAd() returns the next available ad and loads another ad in the background.
InterstitialAd ad = InterstitialAdPreloader.pollAd("AD_UNIT_ID");

if (ad != null) {
  // [Optional] Interact with the ad object as needed.
  ad.setOnPaidEventListener(
      adValue -> {
        // [Optional] Send the impression-level ad revenue information to your preferred
        // analytics server directly within this callback.
      });

  // Show the ad immediately.
  ad.show(activity);
}
InterstitialAdPreloaderSnippets.java

检查预加载广告的可用性

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

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

获取预加载广告的可用性

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

Kotlin

// Verify that a preloaded ad is available.
if (!InterstitialAdPreloader.isAdAvailable("AD_UNIT_ID")) {
  // No ads are available to show.
}
InterstitialAdPreloaderSnippets.kt

Java

// Verify that a preloaded ad is available.
if (!InterstitialAdPreloader.isAdAvailable("AD_UNIT_ID")) {
  // No ads are available to show.
}
InterstitialAdPreloaderSnippets.java

监听预加载广告的可用性

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

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

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

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

Kotlin

// Define a callback to receive preload events.
val callback =
  object : PreloadCallbackV2() {
    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo?) {
      // Called when preloaded ads are available.
    }

    override fun onAdsExhausted(preloadId: String) {
      // Called when no preloaded ads are available.
    }

    override fun onAdFailedToPreload(preloadId: String, adError: AdError) {
      // Called when preloaded ads failed to load.
    }
  }
InterstitialAdPreloaderSnippets.kt

Java

// Define a callback to receive preload events.
PreloadCallbackV2 callback =
    new PreloadCallbackV2() {
      @Override
      public void onAdPreloaded(
          @NonNull String preloadId, @Nullable ResponseInfo responseInfo) {
        // Called when preloaded ads are available.
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        // Called when no preloaded ads are available.
      }

      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull AdError adError) {
        // Called when preloaded ads failed to load.
      }
    };
InterstitialAdPreloaderSnippets.java

停止预加载广告

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

Kotlin

// Stops the preloading and destroy preloaded ads.
InterstitialAdPreloader.destroy("AD_UNIT_ID")
// Stops the preloading and destroy all ads.
InterstitialAdPreloader.destroyAll()
InterstitialAdPreloaderSnippets.kt

Java

// Stops the preloading and destroy preloaded ads.
InterstitialAdPreloader.destroy("AD_UNIT_ID");
// Stops the preloading and destroy all ads.
InterstitialAdPreloader.destroyAll();
InterstitialAdPreloaderSnippets.java

设置缓冲区大小

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

Kotlin

// Define a PreloadConfiguration and buffer up to 3 preloaded ads.
val configuration = PreloadConfiguration.Builder("AD_UNIT_ID").setBufferSize(3).build()
InterstitialAdPreloaderSnippets.kt

Java

// Define a PreloadConfiguration and buffer up to 3 preloaded ads.
PreloadConfiguration configuration =
    new PreloadConfiguration.Builder("AD_UNIT_ID").setBufferSize(3).build();
InterstitialAdPreloaderSnippets.java

预加载缓存限制

Google Mobile Ads SDK (Legacy) 对预加载广告总数强制执行应用级限制 ，该限制适用于所有广告单元和预加载 ID：

• 默认限制：Google Mobile Ads SDK (Legacy) 最多在内存中存储 6 个预加载广告。 此限制适用于所有格式和预加载 ID。
• 我们建议每个预加载 ID 的缓冲区空间保持为 2 或 3。

注意： 如果您的应用可以从增加的应用级限制中受益，请与您的 客户经理联系以请求增加限制。