Banner ads occupy a spot within an app's layout, either at the top or bottom of
the device screen. They stay on screen while users are interacting with the app,
and can refresh automatically after a certain period of time. If you're new to
mobile advertising, they're a great place to start.
[Case study](https://admob.google.com/home/resources/fingersoft-uses-admob-in-app-purchases-to-make-the-most-of-hill-climb-racing/).

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

- Android: `ca-app-pub-3940256099942544/6300978111`
- iOS: `ca-app-pub-3940256099942544/2934735716`

These ad unit IDs have 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

### Configure an `AdView`

Banner ads are displayed in `AdView` objects, so the first step toward
integrating banner ads is to create and position an `AdView`.

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

   ```c++
    #include "firebase/gma/ad_view.h"
   ```
2. Declare and instantiate an `AdView` object:

   ```c++
     firebase::gma::AdView* ad_view;
     ad_view = new firebase::gma::AdView();
   ```
3. Create an `AdSize` and initialize the ad view using the `AdParent` parent
   view. The parent view is a JNI `jobject` reference to an Android `Activity`
   or a pointer to an iOS `UIView` cast to an `AdParent` type:

   ```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 result =
      ad_view->Initialize(ad_parent, kBannerAdUnit, firebase::gma::AdSize::kBanner);
   ```
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 `AdView` 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 = ad_view->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.
     }
   ```
5. 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).

### Set the ad's position

You can set the position of the `AdView` any time after it's initialized:

```c++
firebase::Future<void> result = ad_view->SetPosition(firebase::gma::AdView::kPositionTop);
```

### Load an ad

You can load an ad once the `AdView` has been initialized:

```c++
firebase::gma::AdRequest ad_request;
firebase::Future<firebase::gma::AdResult> load_ad_result = ad_view->LoadAd(my_ad_request);
```

`AdRequest` objects represent a single ad request and contain properties for
information like targeting.

> [!NOTE]
> **Note:** If your ad fails to load, you don't need to explicitly request another one as long as you've configured your ad unit to refresh. The Google Mobile Ads SDK respects any refresh rate you specified in the AdMob UI. If you haven't enabled refresh, you will need to issue a new request.

### Display the ad

Finally, display the ad on the screen by calling `Show()`. This method may be
invoked any time after the ad has been initialized:

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

## Ad events

The Google Mobile Ads C++ SDK provides an `AdListener` class that you can extend
and pass to `AdView::SetListener()` in order to be notified of changes to the ad
view's state.

Extending methods in `AdListener` is optional, so you only need to implement the
methods you want. Below is an example implementation of a class that extends all
of the `AdListener` methods class:

```c++
class ExampleAdListener
    : public firebase::gma::AdListener {
 public:
  ExampleAdListener() {}
  void OnAdClicked() override {
    // This method is invoked when the user clicks the ad.
  }

  void OnAdClosed() override {
   // This method is invoked when the user closes the ad.
  }

  void OnAdImpression() override {
    // This method is invoked when an impression is recorded for an ad.
  }

  void OnAdOpened() override {
    // This method is invoked when an ad opens an overlay that covers the screen.
  }
};

ExampleAdListener* ad_listener = new ExampleAdListener();
ad_view->SetAdListener(ad_listener);
```

## Banner sizes

The table below lists the standard banner sizes.

| Size in points (WxH) | Description | Availability | firebase::gma::AdSize constant |
|---|---|---|---|
| 320x50 | Banner | Phones and Tablets | `kBanner` |
| 320x100 | Large Banner | Phones and Tablets | `kLargeBanner` |
| 300x250 | IAB Medium Rectangle | Phones and Tablets | `kMediumRectangle` |
| 468x60 | IAB Full-Size Banner | Tablets | `kFullBanner` |
| 728x90 | IAB Leaderboard | Tablets | `kLeaderboard` |
| *Provided width* x *Adaptive height* | [Adaptive banner](https://developers.google.com/admob/cpp/banner/anchored-adaptive.md.txt) | Phones and Tablets | N/A |

## Custom ad sizes

To define a custom banner size, set your desired dimensions using the
[`firebase::gma::AdSize`](https://developers.google.com/admob/cpp/reference/class/firebase/gma/ad-size.md.txt)
constructor with width and height parameters, as shown here:

```c++
firebase::gma::AdSize ad_size(/*width=*/320, /*height=*/50);
```

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

### Success stories

- [Sample use case](https://admob.google.com/home/resources/fingersoft-uses-admob-in-app-purchases-to-make-the-most-of-hill-climb-racing/).