> [!WARNING]
> **DEPRECATED:** The Google Mobile Ads C++ SDK is *deprecated* as of June 17, 2024 and should not be adopted in projects that don't already use it. It will enter *End-of-Maintenance (EoM)* on June 17, 2025. Note that versions of the SDK released before the EoM date will continue to function, but no further bug fixes or changes will be released after the EoM date.
>
> Instead of the Google Mobile Ads C++ SDK, consider using the
> [iOS](https://developers.google.com/admob/ios/quick-start.md.txt) and
> [Android](https://developers.google.com/admob/android/quick-start.md.txt) SDKs from AdMob.
> For support, reach out to the
> [contact us form](https://support.google.com/admob/contact/contact_us_gma_sdk).

<br />

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](https://admob.google.com/home/resources/kongregate-uses-admob-to-boost-revenue-average-30-dollar-cpm/),
[case study 2](https://admob.google.com/home/resources/four-thirty-three-uses-admob-to-boost-mobile-game-revenue-15-percent/).

## Prerequisites

- Complete [Get started](https://developers.google.com/admob/cpp/quick-start.md.txt).
- *(Android only)* Familiarity working with JNI `jobject` references (see [Android JNI tips](https://developer.android.com/training/articles/perf-jni)).

## 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](https://developers.google.com/admob/cpp/test-ads.md.txt).

## 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:

   ```c++
    #include "firebase/gma/rewarded_ad.h"
   ```

   <br />

2. Declare and instantiate a `RewardedAd` object:

   ```c++
    firebase::gma::RewardedAd* rewarded_ad;
    rewarded_ad = new firebase::gma::RewardedAd();
   ```

   <br />

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`.

   ```c++
   // 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.

   ```c++
   // 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](https://developers.google.com/admob/cpp/quick-start#futures).

### 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:

```c++
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:

```c++
  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`:

```c++
// 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](https://github.com/firebase/quickstart-cpp/tree/main/gma/testapp)
    in GitHub for an example of logging mediation adapter status.

## Additional resources

### Example in GitHub

- View the source code of our example [quickstart app](https://github.com/firebase/quickstart-cpp/tree/main/gma/testapp) in GitHub.