設定插頁式廣告

選取平台： Android iOS Unity Flutter Android (舊版)

插頁式廣告會全螢幕顯示，覆蓋整個應用程式介面。這類廣告會顯示在應用程式的自然轉換點，例如操作後的空檔或遊戲關卡間的暫停時間。

應用程式顯示插頁式廣告時，使用者可以輕觸廣告繼續，或關閉廣告返回應用程式。

本指南說明如何在 Android 應用程式中整合插頁式廣告。

事前準備

繼續操作前，請先完成下列事項：

• 設定 GMA Next-Gen SDK。
• 使用測試插頁式廣告單元 ID /21775744923/example/interstitial。
  • 建構及測試應用程式時，請務必使用測試廣告，而非實際運作中的廣告，如果未使用測試廣告單元 ID，Google 可能會將您的帳戶停權。
  • 發布應用程式前，請將這個 ID 替換成廣告單元 ID。
  • 如要進一步瞭解 GMA Next-Gen SDK 測試廣告，請參閱「啟用測試廣告」。

瞭解廣告預先載入 (Beta 版)

GMA Next-Gen SDK 的廣告預先載入功能會自動載入及快取廣告。

廣告預先載入有下列優點：

• 參考資料管理：保留參考資料，直到廣告顯示為止。
• 自動重新載入：從快取擷取廣告時，載入新廣告。
• 代管重試：廣告載入失敗時，系統會載入新廣告。
• 過期處理：在廣告過期前重新整理。
• 快取最佳化：最佳化快取順序，放送優先順序最高的廣告。

注意： 如要手動載入廣告，請參閱「載入單一插頁式廣告」一節。

開始預先載入廣告

如要開始預先載入廣告，請在初始化 GMA Next-Gen SDK 時呼叫 start 方法一次。呼叫 start 方法後，GMA Next-Gen SDK 會自動預先載入廣告，並針對預先載入設定重試失敗的要求。

以下範例說明如何開始預先載入廣告：

Kotlin

private fun startPreloading(adUnitId: String) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void startPreloading(String adUnitId) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}

將 AD_UNIT_ID 替換為廣告單元 ID。

上例說明如何使用廣告單元 ID 做為預先載入 ID。預先載入 ID 是您建立的字串 ID，用於識別廣告預先載入設定。如果應用程式需要為同一個廣告單元 ID 設定多個指定目標，請傳遞自訂字串 ID。

廣告預先載入不支援變更指定目標參數或廣告請求。 如需在請求之間變更指定目標參數，請使用單次載入。

取得並顯示預先載入的廣告

顯示廣告前，請呼叫 pollAd 方法。請勿儲存預先載入的廣告物件。呼叫 pollAd 方法時，GMA Next-Gen SDK 會擷取可用的廣告，並自動在背景預先載入下一個廣告。如果沒有可用廣告，GMA Next-Gen SDK 就不會傳回任何廣告。

有可用的廣告物件時，請呼叫 show 方法來顯示廣告。以下範例說明如何擷取及顯示預先載入的廣告：

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)
  if (ad == null) {
    Log.e(TAG, "Interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : InterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Interstitial ad recorded an impression.")
      }
    }
  ad.show(activity)
}

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.e(TAG, "Interstitial ad is not available.");
    return;
  }

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

  // Show the ad.
  ad.show(activity);
}

當應用程式到達廣告刊登位置，且可呼叫 show 方法時，請呼叫 pollAd 方法。請勿在預先載入回呼中，或在檢查 isAdAvailable 方法以保留廣告後，呼叫 pollAd 方法。如需在顯示廣告前檢查廣告中繼資料，請讀取回應資訊，不要從快取中移除廣告。

監聽廣告事件

顯示廣告前，請先監聽廣告事件。以下範例說明如何註冊廣告事件的回呼：

Kotlin

// Listen for ad events.
val ad = interstitialAd
if (ad == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.")
  return
}

ad.adEventCallback =
  object : InterstitialAdEventCallback {
    override fun onAdShowedFullScreenContent() {
      // Interstitial ad did show.
    }

    override fun onAdDismissedFullScreenContent() {
      // Interstitial ad did dismiss.
      interstitialAd = null
    }

    override fun onAdFailedToShowFullScreenContent(
      fullScreenContentError: FullScreenContentError
    ) {
      // Interstitial ad failed to show.
      Log.e(TAG, "Interstitial ad failed to show: ${fullScreenContentError.message}")
    }

    override fun onAdImpression() {
      // Interstitial ad did record an impression.
    }

    override fun onAdClicked() {
      // Interstitial ad did record a click.
    }
  }

Java

// Listen for ad events.
if (interstitialAd == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.");
  return;
}

interstitialAd.setAdEventCallback(
    new InterstitialAdEventCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Interstitial ad did show.
      }

      @Override
      public void onAdDismissedFullScreenContent() {
        // Interstitial ad did dismiss.
        interstitialAd = null;
      }

      @Override
      public void onAdFailedToShowFullScreenContent(
          @NonNull FullScreenContentError fullScreenContentError) {
        // Interstitial ad failed to show.
        Log.e(TAG, "Interstitial ad failed to show: " + fullScreenContentError.getMessage());
      }

      @Override
      public void onAdImpression() {
        // Interstitial ad did record an impression.
      }

      @Override
      public void onAdClicked() {
        // Interstitial ad did record a click.
      }
    });

選用：監聽預先載入期間的事件

開始預先載入廣告時，請註冊預先載入期間的事件，以便在廣告預先載入成功、失敗或廣告快取用盡時收到通知。

以下範例說明如何註冊預先載入廣告事件：

Kotlin

val preloadCallback =
  // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(
        TAG,
        ("Interstitial preload ad $preloadId failed to load with error: ${adError.message}"),
      )
    }

    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)

Java

PreloadCallback preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            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(@NonNull 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(@NonNull String preloadId, @NonNull 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);

廣告載入失敗時，GMA Next-Gen SDK 會自動預先載入廣告，並針對預先載入設定重試失敗的請求。請勿在失敗回呼中叫用手動載入請求。在預先載入期間的事件回呼方法中，請勿呼叫 pollAd、destroy 或 start 方法。在回呼中呼叫這些方法，可能會叫用遞迴載入迴圈。

選用：檢查是否有廣告可用

如要確認是否有廣告可用，請檢查廣告可用性。以下範例說明如何檢查預先載入的廣告是否可用：

Kotlin

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

Java

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

選用：設定緩衝區空間

緩衝區空間會控制記憶體中預先載入的廣告數量。根據預設，Google 會最佳化緩衝區空間，平衡記憶體用量和廣告放送延遲時間。您可以設定自訂緩衝區空間，增加或減少記憶體中保留的廣告數量。建議預先載入兩則廣告。如果大部分流量來自低記憶體裝置，請縮減緩衝區空間。

以下範例說明如何設定緩衝區空間：

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}

預先載入快取限制

GMA Next-Gen SDK 會對所有廣告單元和預先載入 ID，強制執行應用程式層級的預先載入廣告總數上限：

• 預設限制：Google 最多會在記憶體中保留六則預先載入的廣告。這項限制適用於所有格式和預先載入 ID。
• 建議您為每個預先載入 ID 保留兩個緩衝區空間。

注意： 如果提高應用程式層級上限對應用程式有益，請與客戶經理聯絡，要求提高上限。

選用：停止預先載入廣告

應用程式放送廣告時，請保持預先載入功能啟用。在這段期間，請勿呼叫 destroy 方法。如果工作階段中不需要再次顯示特定預先載入 ID 的廣告，可以停止預先載入廣告。如要停止載入特定預先載入 ID 的廣告，請使用預先載入 ID 呼叫 destroy 方法。呼叫 destroy 方法，即可從快取中移除與預先載入 ID 相關聯的所有預先載入廣告。

以下範例說明如何停止預先載入廣告：

Kotlin

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  InterstitialAdPreloader.destroy(adUnitId)
}

Java

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  InterstitialAdPreloader.destroy(adUnitId);
}

選用：閱讀回覆資訊

讀取下一個預先載入廣告的回應資訊，而不從快取中移除廣告。如需在顯示廣告前檢查廣告中繼資料，請讀取回應資訊，不要呼叫 pollAd 方法。

以下範例說明如何讀取下一個預先載入的廣告回應資訊：

Kotlin

val responseInfo = InterstitialAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

Java

ResponseInfo responseInfo = InterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());