此页面由 Cloud Translation API 翻译。

激励广告

通过激励广告，用户可以选择与之互动来换取获取应用内奖励。本指南介绍了如何使用 Google 移动广告 C++ SDK 将激励广告集成到 Android 和 iOS 应用中。

欢迎查看一些客户成功案例：案例研究 1、案例研究 2。

前提条件

完成入门指南。
（仅限 Android）熟悉如何使用 JNI jobject 引用（请参阅 Android JNI 提示）。

务必用测试广告进行测试

在构建和测试应用时，请确保使用的是测试广告，而不是实际投放的广告。否则，可能会导致您的账号被中止。

要加载测试广告，最简便的方法就是使用我们的专用测试广告单元 ID 激励广告（具体数量因设备平台而异）：

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

这些测试广告单元 ID 已经过专门配置，可为每个请求返回测试广告；在编码、测试和调试时，您可以随意在自己的应用中使用它。只需确保在发布应用。

如需详细了解移动广告 SDK 的测试广告如何运作，请参阅测试广告。

实现

植入激励广告的主要步骤如下所示：

加载广告。
注册回调。
展示广告并处理奖励事件。

配置 `RewardedAd`

激励广告显示在 RewardedAd 对象中，因此在应用内集成激励广告的步骤就是创建并初始化一个实例，共 RewardedAd 页。

将以下头文件添加到应用的 C++ 代码中：
```
 #include "firebase/gma/rewarded_ad.h"
```

声明并实例化一个 RewardedAd 对象：

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

使用父视图投射为 AdParent 类型来初始化 RewardedAd 实例。父视图是对 Android 的 JNI jobject 引用 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);

除了将 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 对象。系统会返回一个 firebase::Future，您可以使用该 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 类，才能接收激励广告展示和生命周期事件的通知。您的自定义 FullScreenContentListener 子类可通过 RewardedAd::SetFullScreenContentListener() 方法，它会接收以及当广告成功展示或展示失败时它已关闭

以下代码展示了如何扩展该类并将其分配给广告：

  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 是一次性对象。这意味着，激励广告展示一次后就不能再展示了。最佳做法是在 FullScreenContentListener 的 OnAdDismissedFullScreenContent() 方法中加载另一个激励广告，以便在上一个激励广告关闭后，立即开始加载下一个激励广告。

展示广告并处理奖励事件

在向用户展示激励广告之前，必须为用户提供明确的选项，让用户可以自行选择是否通过观看激励广告内容来换取奖励。激励广告必须始终是一项可由用户自行选择的体验。

展示广告时，您必须提供 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 移动广告 C++ SDK 会完成 Initialize() 返回了 firebase::Future（即使中介广告联盟仍尚未完成初始化。
在获得初始化回调时，如果某些中介广告联盟尚未就绪，该怎么办？: 最佳做法是在 SDK 初始化完成后加载广告。即使中介广告联盟尚未就绪，Google 移动广告 C++ SDK 仍会向该广告联盟请求广告。因此，如果中介广告联盟在超时后完成初始化，它仍然可以在该会话中为将来的广告请求提供服务。; 您可以继续在整个过程中轮询所有适配器的初始化状态您的应用会话中。GetInitializationStatus()
如何找出特定中介广告联盟未准备就绪的原因？: AdapterStatus.description() 描述了适配器未准备好提供服务的原因。请参阅我们的快速入门应用示例，获取记录中介适配器状态的示例。

其他资源

GitHub 中的示例

查看示例的源代码快速入门应用。