Banner Ads

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.

Prerequisites

• Complete Get started.
• (Android only) Familiarity working with JNI jobject references (see Android JNI tips).

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.

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:

    #include "firebase/gma/ad_view.h"

2. Declare and instantiate an AdView object:

     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:

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

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

Set the ad's position

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

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:

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.

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:

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:

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.

Custom ad sizes

To define a custom banner size, set your desired dimensions using the firebase::gma::AdSize constructor with width and height parameters, as shown here:

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

Additional resources

Example in GitHub

• View the source code of our example quickstart app in GitHub.

Success stories

• Sample use case.