Rewarded ads


Rewarded ads let users have the option of interacting with them in exchange for in-app rewards. This guide shows you how to integrate rewarded ads into Android and iOS apps using the Google Mobile Ads C++ SDK.

Read some customer success stories: case study 1, case study 2.

Prerequisites

Always test with test ads

When building and testing your apps, make sure you use test ads rather than live, production ads. Failure to do so can lead to suspension of your account.

The easiest way to load test ads is to use our dedicated test ad unit ID for rewarded ads, which varies per device platform:

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

They've been specially configured to return test ads for every request, and you're free to use it in your own apps while coding, testing, and debugging. Just make sure you replace it with your own ad unit ID before publishing your app.

For more information about how the Mobile Ads SDK's test ads work, see Test Ads.

Implementation

The main steps to integrate rewarded ads are:

  1. Load an ad.
  2. Register for callbacks.
  3. Display the ad and handle the reward event.

Configure a RewardedAd

Rewarded ads are displayed in RewardedAd objects, so the first step toward integrating rewarded ads into your app is to create and initialize an instance of RewardedAd.

  1. Add the following header to your app's C++ code: 

     #include "firebase/gma/rewarded_ad.h"

  2. Declare and instantiate a RewardedAd object: 

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

  3. Initialize the RewardedAd instance using your parent view cast to an AdParent type. The parent view is a JNI jobject reference to an Android Activity or a pointer to an 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. As an alternative to retaining the future as a variable, you can periodically check the status of the initialization operation by invoking InitializeLastResult() on the RewardedAd object. This may be helpful for keeping track of the initialization process in your global game loop.

    // 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.
}

For more information about working with firebase::Future, see Use Futures to monitor the completion status of method calls.

Load an ad

Loading an ad is accomplished using the LoadAd() method on a RewardedAd object. The load method requires that you've initialized the RewardedAd object, and that you have your ad unit ID and an AdRequest object. A firebase::Future is returned which you can use to monitor the state and result of the load operation.

The following code shows how to load an ad once the RewardedAd has been successfully initialized:

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

Register for callbacks

You must extend the FullScreenContentListener class in order to receive notifications of rewarded ad presentation and lifecycle events. Your custom FullScreenContentListener subclass can be registered through the RewardedAd::SetFullScreenContentListener() method, and it will receive callbacks when the ad presents successfully or unsuccessfully as well as when it's dismissed.

The following code shows how to extend the class and assign it to the ad:

  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 is a one-time-use object. This means that once a rewarded ad is shown, it cannot be shown again. A best practice is to load another rewarded ad in the OnAdDismissedFullScreenContent() method of your FullScreenContentListener so that the next rewarded ad starts loading as soon as the previous one is dismissed.

Show the ad and handle the reward event

Before displaying a rewarded ad to users, you must present the user with an explicit choice to view rewarded ad content in exchange for a reward. Rewarded ads must always be an opt-in experience.

When presenting your ad, you must provide a UserEarnedReward object to handle the reward for the user.

The following code shows how to display a 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);

FAQ

Is there a timeout for the initialization call?
After 10 seconds, the Google Mobile Ads C++ SDK completes the firebase::Future returned by Initialize() even if a mediation network still hasn't completed initialization.
What if some mediation networks aren't ready when I get the initialization callback?

It's a best practice to load ads after the SDK initialization has completed. Even if a mediation network is not ready, the Google Mobile Ads C++ SDK will still ask that network for an ad. So if a mediation network finishes initializing after the timeout, it can still service future ad requests in that session.

You can continue to poll the initialization status of all adapters throughout your app session by calling GetInitializationStatus().

How do I find out why a particular mediation network isn't ready?

AdapterStatus.description() describes why an adapter is not ready to service ad requests. See the source code of our example quickstart app in GitHub for an example of logging mediation adapter status.

Additional resources

Example in GitHub