獎勵廣告

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

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

必要條件

• 完成「開始使用」。
• (僅限 Android) 熟悉如何使用 JNI jobject 參照 (請參閱「Android JNI 提示」)。

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

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

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

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

這些 ID 經過特別設定，可針對每項要求傳回測試廣告，您可以在編寫程式碼、測試及偵錯時，自由地在自己的應用程式中使用。發布應用程式前，請務必將其替換成您自己的廣告單元 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，請參閱「使用 Futures 監控方法呼叫的完成狀態」。

載入廣告

如要載入廣告，請使用 RewardedAd 物件的 LoadAd() 方法。載入方法需要您已初始化 RewardedAd 物件，且您擁有廣告單元 ID 和 AdRequest 物件。系統會傳回 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 中的範例

• 在 GitHub 中查看範例快速入門應用程式的原始碼。