广告预加载(Beta 版)

广告预加载是 Google Mobile Ads SDK (Legacy) 中由 Google 管理的广告加载功能,可代表您管理广告加载和缓存。广告预加载需要您更改广告加载的管理方式。如需通过广告预加载来优化效果,请停用自定义缓存,并将该职责委托给 Google Mobile Ads SDK (Legacy)。

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

  • 引用管理:保留已加载的广告,这样您就不必在准备好展示广告之前维护引用。
  • 自动重新加载:当您从缓存中提取广告时,系统会自动加载新广告。
  • 代管式重试:使用指数退避算法自动重试失败的请求。
  • 过期处理:在广告过期(通常为 1 小时)之前自动刷新广告。
  • 缓存优化:如果您使用的缓存大小大于 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)

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);

请将 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)

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

检查预加载广告的可用性

如需检查广告是否可用,请选择以下任一选项:

获取预加载广告的可用性

以下示例会检查广告可用性:

Kotlin

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

Java

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

监听预加载的广告是否可供展示

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

预加载事件旨在用于分析目的。在预加载事件回调中:

  • 不要调用 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.
    }
  }

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.
      }
    };

停止预加载广告

如果您不需要在会话中再次展示预加载 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()

Java

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

设置缓冲区空间

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

Kotlin

// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val configuration = PreloadConfiguration.Builder("AD_UNIT_ID").setBufferSize(2).build()

Java

// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
PreloadConfiguration configuration =
    new PreloadConfiguration.Builder("AD_UNIT_ID").setBufferSize(2).build();

预加载缓存限制

Google Mobile Ads SDK (Legacy) 会针对所有广告单元和预加载 ID 的预加载广告总数,统一设定并执行应用级上限:

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