激励视频广告

您可以使用 AdMob 通过 AdMob 中介在您的 C++ 应用中展示激励视频广告。

本指南将向您介绍如何请求和展示激励视频广告，如何确定激励视频广告何时可用，以及如何奖励用户。

前提条件

在开始与激励视频广告 C++ API 进行交互之前，您需要在自己的应用中加入中介网络适配器和 SDK，您将通过这些适配器和 SDK 投放激励视频广告。 如需了解向您的应用中添加激励视频广告中介的步骤，可参阅适用于 iOS 和 Android 的发布商激励视频广告指南。

如果这是您第一次在 C++ 应用中设置 AdMob 和 Firebase，请参阅 AdMob C++ 入门指南，以了解有关如何将您的应用与 AdMob 和 Firebase 集成的分步说明。

与 rewarded_video 命名空间进行交互

rewarded_video 命名空间中包含了通过 Google Mobile Ads SDK 展示激励视频广告的方法。横幅广告和插页式广告均拥有自己的对象，与它们不同的是，激励视频广告是通过 rewarded_video 命名空间中的静态方法控制的。

如需访问 rewarded_video 命名空间，请将以下 include 语句添加到应用的 C++ 代码中：

#include "firebase/admob/rewarded_video.h"

以下是与 rewarded_video 命名空间交互的基本步骤：

  1. 调用 Initialize() 以初始化库和中介适配器：

    firebase::admob::rewarded_video::Initialize();

  2. 在库和中介适配器均初始化后，您即可通过调用 LoadAd() 来加载激励视频广告：

    firebase::admob::AdRequest my_ad_request;
// Set some or all of the member variables in the AdRequest struct.
firebase::admob::rewarded_video::LoadAd("YOUR_REWARDED_AD_UNIT_ID", my_ad_request);

    如需查看有关如何定位和自定义广告请求的示例，请参阅创建 AdMob 广告请求。

  3. 激励视频广告加载完毕后，调用 Show() 向用户展示该视频广告：

    // my_ad_parent is a reference to an iOS UIView or an Android Activity. This is
// the parent UIView or Activity of the rewarded video.
firebase::admob::rewarded_video::Show(my_ad_parent);

  4. 根据需要重复第 2 步和第 3 步。

  5. 调用 Pause() 可暂停与激励视频广告相关的任何后台处理过程：

    firebase::admob::rewarded_video::Pause();

    每当 C++ 引擎暂停或应用失去焦点时，请调用此方法。

  6. 调用 Resume() 即可从暂停状态恢复，例如当用户从 Google Play 返回到您的应用时：

    firebase::admob::rewarded_video::Resume();

  7. 当您已在应用中完成了激励视频广告的展示后，调用 Destroy() 以清理和释放激励视频广告命名空间占用的所有资源：

    firebase::admob::rewarded_video::Destroy();

上述步骤着重介绍您的应用在加载和展示激励视频广告时使用的基本方法调用。然而，在调用这些方法前先监测之前的方法调用的完成状态，才是最好的做法。下一部分将介绍如何使用 Future 来确定之前 rewarded_video 命名空间方法调用的完成状态。

使用 Future 来监控方法调用的完成状态

Future 为您提供了一种用来确定您之前 rewarded_video 方法调用的完成状态的方法。例如，当调用 rewarded_video::Initialize() 方法时，系统会创建并返回一个新的 Future。如需了解详情，请参阅 firebase::Future。应用可以通过轮询 Future 的状态来确定初始化的完成时间。当 Future 变成已完成状态后，您就可以加载激励视频广告了。

rewarded_video 命名空间中的大多数方法都有一个对应的“last result”（上次结果）方法，应用可以使用这一方法来获取给定操作的最新 Future。例如，Initialize() 方法就有一个名为 InitializeLastResult() 的对应方法，可以返回最近一次调用 Initialize() 后得到的 Future：

if (firebase::admob::rewarded_video::InitializeLastResult().status() ==
    firebase::kFutureStatusComplete &&
    firebase::admob::rewarded_video::InitializeLastResult().error() ==
    firebase::admob::kAdMobErrorNone) {
  firebase::admob::rewarded_video::LoadAd("YOUR_REWARDED_AD_UNIT_ID",
      my_ad_request);
}

使用 LoadAdLastResult() 方法可以获取一个表示上次调用 LoadAd() 方法后的状态的 Future。如果其状态为已完成，那么您就可以在应用下一次自然停顿点展示激励视频广告：

if (firebase::admob::rewarded_video::LoadAdLastResult().status() ==
    firebase::kFutureStatusComplete &&
    firebase::admob::rewarded_video::LoadAdLastResult().error() ==
    firebase::admob::kAdMobErrorNone) {
  // my_ad_parent is a reference to an iOS UIView or an Android Activity.
  // This is the parent UIView or Activity of the rewarded video.
  firebase::admob::rewarded_video::Show(my_ad_parent);
}

使用侦听器来接收广告生命周期事件通知

AdMob rewarded_video 命名空间提供了一个 Listener 抽象类，您可以继承该类并将其传递给 SetListener() 方法，以便接收有关奖励和激励视频广告演示状态更改的通知。

下面是继承了 Listener 抽象类的一个类的示例实现代码：

// A simple listener that logs changes to rewarded video state.
class LoggingRewardedVideoListener
    : public firebase::admob::rewarded_video::Listener {
 public:
  LoggingRewardedVideoListener() {}
  void OnRewarded(firebase::admob::rewarded_video::RewardItem reward) override {
    LogMessage("Rewarding user with %f %s.", reward.amount,
               reward.reward_type.c_str());
  }
  void OnPresentationStateChanged(
      firebase::admob::rewarded_video::PresentationState state) override {
    LogMessage("Rewarded video PresentationState has changed to %d.", state);
  }
};

// After calling Initialize and waiting for the Initialize future to complete
// successfully, set the listener.
LoggingRewardedVideoListener rewarded_video_listener;
firebase::admob::rewarded_video::SetListener(&rewarded_video_listener);

轮询奖励

rewarded_video 命名空间还提供 PollableRewardListener，这是一个可以实例化并传递给 SetListener() 方法的类。 这个类提供了一种无需继承 Listener 抽象类也可访问奖励的替代方式。

基于轮询的侦听器使用一个队列来维护 Mobile Ads SDK 授予的奖励，您可以在以后检索到这些奖励。PollableRewardListener 的 PollReward(RewardItem* reward) 方法会弹出队列中最早的奖励，并将其数据复制到已提供的 RewardItem 结构中。

以下是使用 rewarded_video::PollableRewardListener 类来轮询奖励的示例实现代码：

// After calling Initialize and waiting for the Initialize future to complete
// successfully, instantiate a PollableRewardListener object and set the listener.
firebase::admob::rewarded_video::PollableRewardListener* listener =
    new firebase::admob::rewarded_video::PollableRewardListener();

// Pass the PollableRewardListener object to the SetListener method.
firebase::admob::rewarded_video::SetListener(listener);

...
// Display the rewarded videos to users so they can earn rewards.
...

// Declare a RewardItem struct. Pass this RewardItem struct by reference to
// the PollReward method.
firebase::admob::rewarded_video::RewardItem reward;
// Call the PollReward method to see if a reward is available.
while (listener->PollReward(&reward)) {
  // A reward is available. Do something with the reward.
  printf("Reward user with %f %s.", reward.amount, reward.reward_type);
}

简单的游戏循环示例

下面是一个简单的游戏循环，它使用状态机来跟踪对 rewarded_video 命名空间的方法调用：

namespace rewarded_video = firebase::admob::rewarded_video;

enum State {
  kNextStepInitialize,
  kNextStepLoadAd,
  kNextStepShowAd,
  kNextStepRewardUser,
  kNextStepRestartGame
}

// Instantiate a PollableRewardListener object.
firebase::admob::rewarded_video::PollableRewardListener* listener =
    new firebase::admob::rewarded_video::PollableRewardListener();

State state = kNextStepInitialize;
for ( ; ; ) /* game loop */ {
  switch (state) {
    case kNextStepInitialize:
      rewarded_video::Initialize();
      state = kNextStepLoadAd;
      break;
    case kNextStepLoadAd:
      if (rewarded_video::InitializeLastResult().status() ==
          firebase::kFutureStatusComplete &&
          rewarded_video::InitializeLastResult().error() ==
          firebase::admob::kAdMobErrorNone) {
        // Pass the PollableRewardListener object to the SetListener method.
        firebase::admob::rewarded_video::SetListener(listener);
        rewarded_video::LoadAd("YOUR_REWARDED_AD_UNIT_ID",
                               my_ad_request);
      }
      state = kNextStepShowAd;
      break;
    case kNextStepShowAd:
      if (rewarded_video::LoadAdLastResult().status() ==
          firebase::kFutureStatusComplete &&
          rewarded_video::LoadAdLastResult().error() ==
          firebase::admob::kAdMobErrorNone) {
        rewarded_video::Show(my_ad_parent);
      }

      if (rewarded_video::ShowLastResult().status() ==
          firebase::kFutureStatusComplete &&
          rewarded_video::ShowLastResult().error() ==
          firebase::admob::kAdMobErrorNone &&
          rewarded_video::presentation_state() ==
          rewarded_video::kPresentationStateHidden) {
        // If the rewarded video has been displayed to the user and
        // the user closed the ad, then reward the user.
        state = kNextStepRewardUser;
      }
      break;
    case kNextStepRewardUser:
      firebase::admob::rewarded_video::RewardItem reward;
      // Call the PollReward method to see if a reward is available.
      while (listener->PollReward(&reward)) {
        // A reward is available. Do something with the reward.
        printf("Reward user with %f %s.", reward.amount, reward.reward_type);
      }
      state = kNextStepRestartGame;
      break;
    case kNextStepRestartGame:
      // restart game
      break;
  }

  // render game
}

后续步骤

如需详细了解激励视频广告，请参阅 iOS 激励视频广告和 Android 激励视频广告入门指南。