Rewarded Video

You can use AdMob to display rewarded videos in your C++ apps via AdMob mediation.

This guide shows you how to request and display a rewarded video, determine when rewarded videos are available, and reward the user.

Prerequisites

Before you start interacting with the rewarded video C++ API, you need to include the mediation network adapters and SDKs in your app that you want to serve rewarded videos from. You can see the steps for adding rewarded video mediation to your app in the iOS rewarded video Get Started guide and the Android rewarded video Get Started guide.

Also, if this is your first time setting up AdMob and Firebase in your C++ app, check out the AdMob C++ Get Started guide for step-by-step instructions on integrating your app with AdMob and Firebase.

Interact with the rewarded_video namespace

The rewarded_video namespace contains methods to display rewarded videos via the Google Mobile Ads SDK. Unlike banner and interstitial ads, which have their own objects, rewarded videos are controlled using static methods in the rewarded_video namespace.

To access the rewarded_video namespace, add the following include to your app's C++ code:

#include "firebase/admob/rewarded_video.h"

Here are the basic steps for interacting with the rewarded_video namespace:

Call Initialize() to initialize the library and mediation adapters:
```
firebase::admob::rewarded_video::Initialize();
```
Note: Initialize() must be the very first method called.
Now that the library and mediation adapters have been initialized, you are ready to call LoadAd() to load a rewarded video:
```
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);
```
See Create an AdMob ad request for an example on targeting and customizing ad requests.

Once the rewarded video has loaded, call Show() to display the video to the user:

// 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);

Repeat steps 2 and 3 as needed.
Call Pause() to pause any background processing associated with rewarded video:
```
firebase::admob::rewarded_video::Pause();
```
Call this method whenever the C++ engine pauses or the application loses focus.
Call Resume() to resume from a pause, for example, when the user returns to your app from Google Play:
```
firebase::admob::rewarded_video::Resume();
```
When you are finished displaying rewarded video ads in your app, call Destroy() to clean up and deallocate any resources used by the rewarded video namespace:
```
firebase::admob::rewarded_video::Destroy();
```
Note: No other methods in the rewarded_video namespace should be called once this method has been invoked.

The steps above highlight the basic method calls for your app to use when loading and displaying a rewarded video. However, it's best practice to monitor the completion status of previous method calls before calling them. The next section describes the steps for using Futures to determine the completion status of previous rewarded_video namespace method calls.

Use Futures to monitor the completion status of method calls

Futures provide you with a way to determine the completion status of your previous rewarded_video namespace method calls. When a call is made to the rewarded_video::Initialize() method, for example, a new Future is created and returned. See firebase::Future for more details. Apps can poll the status of the Future to determine when the initialization has completed. Once the Future is complete, you're ready to load the rewarded video.

Most methods in the rewarded_video namespace have a corresponding "last result" method that apps can use to retrieve the most recent Future for a given action. The Initialize() method, for example, has a method called InitializeLastResult() that returns the Future for the most recent call to Initialize():

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);
}

Use the LoadAdLastResult() method to get a Future representing the status of the last call to the LoadAd() method. If its status is complete, then you can display the rewarded video at the next natural stopping point in your app:

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);
}

Use a listener to be notified of ad lifecycle events

The AdMob rewarded_video namespace provides an abstract Listener class that you can extend and pass to the SetListener() method to be notified of rewards and rewarded video presentation state changes.

Below is an example implementation of a class that extends the Listener abstract class:

// 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);

Poll rewards

The rewarded_video namespace also provides PollableRewardListener, a class that you can instantiate and pass to the SetListener() method. This class provides an alternative option for accessing rewards without having to extend the abstract Listener class.

The polling-based listener uses a queue to maintain awards granted by the Mobile Ads SDK that can be retrieved at a later time. The PollReward(RewardItem* reward) method of the PollableRewardListener pops the oldest queued reward and copies its data into the provided RewardItem struct.

Here's an example implementation for polling rewards using the rewarded_video::PollableRewardListener class:

// 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);
}

Simple game loop example

Here's a simple game loop that uses a state machine to keep track of method calls to the rewarded_video namespace:

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::GetPresentationState() ==
          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
}

What's next

See the iOS Rewarded Video and the Android Rewarded Video Get Started guides for more information on Rewarded Video ads.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated September 22, 2016.