> [!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 />

Interstitial ads are full-screen ads that cover the interface of an app until
closed by the user. They're typically displayed at natural transition points in
the flow of an app, such as between activities or during the pause between
levels in a game. When an app shows an interstitial ad, the user has the choice
to either tap on the ad and continue to its destination or close it and return
to the app.
[Case study](https://admob.google.com/home/resources/freaking-math-powers-revenue-increase-with-google-admob-support/).

This guide shows you how to integrate interstitial ads into Android and iOS apps
using the Google Mobile Ads C++ SDK.

## 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
interstitials, which varies per device platform:

- Android: `ca-app-pub-3940256099942544/1033173712`
- iOS: `ca-app-pub-3940256099942544/4411468910`

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 interstitial ads are:

1. Load an ad.
2. Register for callbacks.
3. Display the ad and handle its lifecycle events.

### Configure an `InterstitialAd`

Interstitial ads are displayed in `InterstitialAd` objects, so the first step
toward integrating interstitial ads into your app is to create and initialize an
`InterstitialAd` object.

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

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

   <br />

2. Declare and instantiate an `InterstitialAd` object:

   ```c++
    firebase::gma::InterstitialAd* interstitial_ad;
    interstitial_ad = new firebase::gma::InterstitialAd();
   ```

   <br />

3. Initialize the `InterstitialAd` 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 = interstitial_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 `InterstitialAd` 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 = interstitial_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 the
`InterstitialAd` object. The load method requires that you've initialized the
`InterstitialAd` 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 `InterstitialAd` has been
successfully initialized:

```c++
firebase::gma::AdRequest ad_request;
firebase::Future<firebase::gma::AdResult> load_ad_result;
load_ad_result = interstitial_ad->LoadAd(interstitial_ad_unit_id, ad_request);
```

### Register for callbacks

You must extend the `FullScreenContentListener` class in order to receive
notifications of interstitial ad presentation and lifecycle events. Your custom
`FullScreenContentListener` subclass can be registered through the
`InterstitialAd::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* full_screen_content_listener =
    new ExampleFullScreenContentListener();
  interstitial_ad->SetFullScreenContentListener(full_screen_content_listener);
```

`InterstitialAd` is a one-time-use object. This means that once an interstitial
ad is shown, it cannot be shown again. A best practice is to load another
interstitial ad in the `OnAdDismissedFullScreenContent()` method of your
`FullScreenContentListener` so that the next interstitial ad starts loading as
soon as the previous one is dismissed.

### Display the ad

Interstitials should be displayed during natural pauses in the flow of an app.
Between levels of a game is a good example, or after the user completes a task.
While the `FullScreenContentListener` can be used to determine when an ad has
shown its full screen content, the future returned by `Show()` will also signal
when the ad has been successfully shown.

```c++
  firebase::Future<void> result = interstitial_ad->Show();
```

## Best practices

Consider whether interstitial ads are the right type of ad for your app.
:   Interstitial ads work best in apps with natural transition points. The
    conclusion of a task within an app, like sharing an image or completing a game
    level, creates such a point. Because the user is expecting a break in the
    action, it's easy to present an interstitial ad without disrupting their
    experience. Make sure you consider at which points in your app's workflow you'll
    display interstitial ads and how the user is likely to respond.

Remember to pause the action when displaying an interstitial ad.
:   There are a number of different types of interstitial ads: text, image,
    video, and more. It's important to make sure that when your app displays an
    interstitial ad, it also suspends its use of some resources to allow the ad to
    take advantage of them. For example, when you make the call to display an
    interstitial ad, be sure to pause any audio output being produced by your app.
    You can resume playing sounds in the `OnAdDismissedFullScreenContent` method of
    your installed `FullScreenContentListener` which will be invoked when the user
    has finished interacting with the ad. In addition, consider temporarily halting
    any intense computation tasks (such as a game loop) while the ad is being
    displayed. This will ensure that the user doesn't experience slow or
    unresponsive graphics or stuttered video.

Allow for adequate loading time.
:   Just as it's important to make sure you display interstitial ads at an
    appropriate time, it's also important to make sure the user doesn't have to wait
    for them to load. Loading the ad in advance before you intend to show can ensure
    that your app has a fully loaded interstitial ad at the ready when the time
    comes to display one.

Don't flood the user with ads.
:   While increasing the frequency of interstitial ads in your app might seem
    like a great way to increase revenue, it can also degrade the user experience
    and lower clickthrough rates. Make sure that users aren't so frequently
    interrupted that they're no longer able to enjoy the use of your app.

Don't use the load completion future to show the interstitial.
:   This can cause a poor user experience. Instead, pre-load the ad before you
    need to show it.

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

### Mobile Ads Garage video tutorials

- [Interstitial best practices](https://www.youtube.com/watch?v=r2RgFD3Apyo&index=5&list=PLOU2XLYxmsIKX0pUJV3uqp6N3NeHwHh0c)

### Success stories

- [Sample use case](https://admob.google.com/home/resources/freaking-math-powers-revenue-increase-with-google-admob-support/)

## Next steps

- If you haven't already, create your own interstitial ad unit in the [AdMob UI](https://apps.admob.com/).
- Learn about [ad targeting](https://developers.google.com/admob/cpp/targeting.md.txt) and [interstitial ad guidelines](https://support.google.com/admob/answer/6066980).