獎勵廣告


使用者可選擇與獎勵廣告互動，換取應用程式內獎勵。本指南說明如何使用 Google Mobile Ads C++ SDK，將獎勵廣告整合至 Android 和 iOS 應用程式。

閱讀一些客戶成功案例：個案研究 1、個案研究 2。

必要條件

一律使用測試廣告進行測試

建構及測試應用程式時，請務必使用測試廣告，而非實際的正式版廣告。否則帳戶可能會遭到停權。

如要載入測試廣告，最簡單的方法是使用獎勵廣告專用的測試廣告單元 ID，這會因裝置平台而異：

  • Android：ca-app-pub-3940256099942544/5224354917
  • iOS：ca-app-pub-3940256099942544/1712485313

已設定為針對每次請求傳回測試廣告 您可以在自己的應用程式中自由使用這項 API，編寫程式碼、進行測試及偵錯。 請務必在發布應用程式前，將其替換為您自己的廣告單元 ID。

如要進一步瞭解 Mobile Ads SDK 的測試廣告運作方式，請參閱「測試廣告」一文。

導入作業

整合獎勵廣告的主要步驟如下：

  1. 載入廣告。
  2. 註冊回呼。
  3. 顯示廣告並處理獎勵事件。

設定 RewardedAd

獎勵廣告會顯示在 RewardedAd 物件中，因此首先要前往 建立並初始化執行個體，就是將獎勵廣告整合至應用程式 (共 RewardedAd 個)。

  1. 將下列標頭加入應用程式的 C++ 程式碼中：

     #include "firebase/gma/rewarded_ad.h"

  2. 宣告 RewardedAd 物件並例項化： 

     firebase::gma::RewardedAd* rewarded_ad;
 rewarded_ad = new firebase::gma::RewardedAd();

  3. 使用父項檢視畫面轉換為 AdParent 類型，初始化 RewardedAd 例項。父項檢視畫面是 JNI jobject 對 Android Activity 的參照，或指向 iOS UIView的指標。

    // my_ad_parent is a jobject reference to an Android Activity or
// a pointer to an iOS UIView.
firebase::gma::AdParent ad_parent =
  static_cast<firebase::gma::AdParent>(my_ad_parent);
firebase::Future<void> result = rewarded_ad->Initialize(ad_parent);

  4. 除了將 Future 保留為變數之外，您也可以定期 透過叫用 RewardedAd 物件的 InitializeLastResult()。這可能有助於追蹤全域遊戲迴圈中的初始化程序。

    // Monitor the status of the future in your game loop:
firebase::Future<void> result = rewarded_ad->InitializeLastResult();
if (result.status() == firebase::kFutureStatusComplete) {
  // Initialization completed.
  if(future.error() == firebase::gma::kAdErrorCodeNone) {
    // Initialization successful.
  } else {
    // An error has occurred.
  }
} else {
  // Initialization on-going.
}

如要進一步瞭解如何使用 firebase::Future，請參閱 使用 Future 監控方法的完成狀態 呼叫。

載入廣告

載入廣告的方式是在 RewardedAd 物件上使用 LoadAd() 方法。使用載入方法前，您必須先將 RewardedAd 初始化 物件，而且已有廣告單元 ID 和 AdRequest 物件。A 罩杯 系統會傳回 firebase::Future，方便您監控狀態和結果 載入作業的狀態。

以下程式碼說明如何在 RewardedAd 成功初始化後載入廣告：

firebase::gma::AdRequest ad_request;
firebase::Future<firebase::gma::AdResult> load_ad_result;
load_ad_result = rewarded_ad->LoadAd(rewarded_ad_unit_id, ad_request);

註冊回呼

您必須擴充 FullScreenContentListener 類別才能接收 獎勵廣告展示和生命週期事件的通知。您可以透過 RewardedAd::SetFullScreenContentListener() 方法註冊自訂 FullScreenContentListener 子類別，這樣一來，當廣告成功或失敗顯示，以及遭到關閉時，系統就會收到回呼。

以下程式碼說明如何擴充類別並指派給廣告：

  class ExampleFullScreenContentListener
      : public firebase::gma::FullScreenContentListener {

   public:
    ExampleFullScreenContentListener() {}

    void OnAdClicked() override {
      // This method is invoked when the user clicks the ad.
    }

    void OnAdDismissedFullScreenContent() override {
     // This method is invoked when the ad dismisses full screen content.
    }

    void OnAdFailedToShowFullScreenContent(const AdError& error) override {
      // This method is invoked when the ad failed to show full screen content.
      // Details about the error are contained within the AdError parameter.
    }

    void OnAdImpression() override {
      // This method is invoked when an impression is recorded for an ad.
    }

    void OnAdShowedFullScreenContent() override {
      // This method is invoked when the ad showed its full screen content.
    }
  };

  ExampleFullScreenContentListener* example_full_screen_content_listener =
    new ExampleFullScreenContentListener();
  rewarded_ad->SetFullScreenContentListener(example_full_screen_content_listener);

RewardedAd 是一次性的物件。這表示當獎勵廣告 系統現在無法再次顯示最佳做法是載入其他獎勵廣告 在您中的 OnAdDismissedFullScreenContent() 方法中 FullScreenContentListener，下一則獎勵廣告很快就會開始載入 因為上一個選項會關閉

顯示廣告並處理獎勵事件

向使用者顯示獎勵廣告之前，請務必 明確選擇觀看獎勵廣告以換取獎勵。獎勵廣告 廣告都必須是使用者主動選擇使用的體驗。

在呈現廣告時，您必須提供 UserEarnedReward 物件，以便為使用者處理獎勵。

以下程式碼說明如何顯示 RewardedAd：

// A simple listener track UserEarnedReward events.
class ExampleUserEarnedRewardListener :
    public firebase::gma::UserEarnedRewardListener {
 public:
   ExampleUserEarnedRewardListener() { }

  void OnUserEarnedReward(const firebase::gma::AdReward& reward) override {
    // Reward the user!
  }
};

ExampleUserEarnedRewardListener* user_earned_reward_listener =
  new ExampleUserEarnedRewardListener();
firebase::Future<void> result = rewarded_ad->Show(user_earned_reward_listener);

常見問題

初始化呼叫是否有逾時？
10 秒後，即使中介服務聯播網仍未完成初始化，Google Mobile Ads C++ SDK 也會完成 Initialize() 傳回的 firebase::Future。
如果我收到初始化回呼時，有些中介服務聯播網還沒準備就緒，該怎麼辦？

最佳做法是在 SDK 初始化完成後載入廣告。即使中介服務聯播網尚未就緒，Google Mobile Ads C++ SDK 仍會向該聯播網要求廣告。如果中介服務聯播網結束了 它仍可在逾時後執行初始化，以繼續處理日後的廣告請求 會很有幫助

您可以持續輪詢所有轉接程式的初始化狀態 呼叫 GetInitializationStatus() 來修正應用程式工作階段。

如何找出特定中介服務聯播網尚未準備就緒的原因？

AdapterStatus.description() 說明轉接器為何無法處理廣告要求。如需瞭解如何記錄中介服務適配器狀態，請參閱 GitHub 中的快速入門應用程式範例的原始碼。

其他資源

GitHub 中的範例