設定獎勵廣告

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

透過獎勵廣告，您可以在使用者與影片廣告/可試玩廣告互動或填寫問卷調查後，提供應用程式內商品做為獎勵。

本指南說明如何將獎勵廣告整合至 Android 應用程式。

事前準備

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

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

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

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

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

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

注意： 如要手動載入廣告，請參閱「載入單一獎勵廣告」一文。

開始預先載入廣告

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

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

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.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 = RewardedAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded ad recorded an impression.")
      }
    }
  ad.show(activity) { rewardItem -> Log.d(TAG, "User earned reward: ${rewardItem.amount}") }
}

Java

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  final RewardedAd ad = RewardedAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not available.");
    return;
  }

  Log.d(TAG, "Rewarded ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Rewarded ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(
      activity,
      rewardItem -> {
        Log.d(TAG, "User earned reward: " + rewardItem.getAmount());
      });
}

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

監聽廣告事件

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

Kotlin

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = rewardedAd
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not ready yet.")
    return
  }

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

      override fun onAdDismissedFullScreenContent() {
        // Rewarded ad did dismiss.
        rewardedAd = null
      }

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

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

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

Java

private void listenToAdEvents() {
  // Listen for ad events.
  if (rewardedAd == null) {
    Log.e(TAG, "Rewarded ad is not ready yet.");
    return;
  }

  rewardedAd.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded ad did show.
        }

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

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

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

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

選用：驗證伺服器端驗證 (SSV) 回呼

如要在伺服器端驗證 (SSV) 回呼中傳遞使用者和應用程式背景資訊，請在顯示廣告前，先在廣告物件上設定驗證選項。由於 SSV 回呼是從 Google 傳送至伺服器，不含工作階段狀態，因此請附加下列選用字串。Google 會將這些字串原封不動地轉送，做為 SSV 回呼中已簽署的查詢參數。

• user_id 查詢參數：識別要獎勵的使用者，例如內部帳戶 ID。
• custom_data 查詢參數：包含應用程式資料，例如獎勵刊登位置、遊戲關卡或伺服器產生的 Nonce。

如未設定值，Google 會從 SSV 回呼中省略該查詢參數。

以下範例說明如何在顯示廣告前，設定廣告物件的自訂資料：

Kotlin

RewardedAd.load(
  context,
  AD_UNIT_ID,
  AdRequest.Builder().build(),
  object : RewardedAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedAd) {
      rewardedAd = ad
      val options =
        ServerSideVerificationOptions.Builder().setCustomData("SAMPLE_CUSTOM_DATA_STRING").build()
      rewardedAd?.setServerSideVerificationOptions(options)
    }
  },
)

Java

RewardedAd.load(
    context,
    AD_UNIT_ID,
    new AdRequest.Builder().build(),
    new RewardedAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedAd ad) {
        rewardedAd = ad;
        ServerSideVerificationOptions options =
            new ServerSideVerificationOptions.Builder()
                .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
                .build();
        rewardedAd.setServerSideVerificationOptions(options);
      }
    });

將 SAMPLE_CUSTOM_DATA_STRING 替換成自訂資料。

重點：custom_data 查詢參數會以百分比符號編碼。剖析值之前，請先在伺服器上對字串進行網址解碼，並驗證回呼簽章，再信任 user_id 或 custom_data 查詢參數。

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

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

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

Kotlin

val preloadCallback =
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(TAG, "Rewarded preload ad $preloadId failed to load with error: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded preload ad $preloadId is not available")
    }

    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
      Log.i(TAG, "Rewarded preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

Java

PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
      }

      @Override
      public void onAdsExhausted(String preloadId) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is not available");
      }

      @Override
      public void onAdPreloaded(String preloadId, ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is available");
      }
    };

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

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

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

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

Kotlin

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

Java

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

選用：設定緩衝區空間

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

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

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

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);
RewardedAdPreloader.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.
  RewardedAdPreloader.destroy(adUnitId)
}

Java

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

選用：閱讀回覆資訊

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

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

Kotlin

val responseInfo = RewardedAdPreloader.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 = RewardedAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

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