廣告預先載入 (Alpha 版)

選取平台： Android (Beta 版) Android iOS Unity

警告：這項功能僅開放部分帳戶使用。如需存取權，請與客戶經理聯絡。

廣告預先載入是 GMA Next-Gen SDK 中由 Google 管理的廣告載入功能，可代您管理廣告載入和快取。如要預先載入廣告，您必須變更廣告載入的管理方式。如要使用廣告預先載入功能提升成效，請停用自訂快取，並將這項責任委派給 GMA Next-Gen SDK。

相較於手動載入廣告，廣告預先載入具有下列優點：

• 參照管理：保存已載入的廣告，因此您不必維護參照，直到準備好顯示廣告為止。
• 自動重新載入：從快取中取出廣告時，系統會自動載入新廣告。
• 管理重試：使用指數輪詢自動重試失敗的要求。
• 到期處理：在廣告到期前 (通常是一小時後) 自動重新整理廣告。
• 快取最佳化：如果使用的快取大小超過一，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 會調整緩衝區大小，以平衡記憶體用量和廣告放送延遲。如果應用程式會在載入下一個廣告前顯示廣告，您可以設定自訂緩衝區大小，增加記憶體中保留的廣告數量。建議緩衝區大小最多為四。

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