Get Started

This guide is for publishers who want to monetize a C++ app with AdMob, without using Firebase. If you plan to include Firebase in your app—or if you're considering it—see the AdMob with Firebase version of this guide instead.

Integrating the Google Mobile Ads C++ SDK into an app is the first step toward displaying ads and earning revenue. Once you've integrated the SDK, you can choose an ad format, such as interstitial or rewarded, and follow the steps to implement it.

The Google Mobile Ads C++ SDK wraps the Google Mobile Ads iOS and Android SDKs, and is only available on those platforms. The Google Mobile Ads C++ SDK makes use of Firebase C++ constructs to support asynchronous operations, so it resides in the firebase::gma namespace.

If this is your first time going through this guide, we recommend that you download and follow along using the Google Mobile Ads C++ test app.

Prerequisites

Android

  • Use Android Studio 3.2 or higher
  • Make sure that your app's build file uses the following values:
    • A minSdkVersion of 16 or higher
    • A compileSdkVersion of 28 or higher

iOS

  • Use Xcode 13 or higher
  • Target iOS 10.0 or higher

Set up your app in your AdMob account

Register your app as an AdMob app by completing the following steps:

  1. Sign in to or sign up for an AdMob account.

  2. Register your app with AdMob. This step creates an AdMob app with a unique AdMob app ID that is needed later in this guide.

Install the Google Mobile Ads C++ SDK

Since the Google Mobile Ads C++ SDK resides in the firebase::gma namespace, download the Firebase C++ SDK, and then unzip it to a directory of your choice.

The Firebase C++ SDK is not platform-specific, but it does require platform-specific library configurations.

Android

We recommend using CMake, but you can find instructions for ndk-build in our general Firebase C++ SDK Get Started Guide to link libfirebase_app.a and libfirebase_gma.a to your app.

  1. In your project's gradle.properties file, specify the location of the unzipped SDK:

    systemProp.firebase_cpp_sdk.dir=FULL_PATH_TO_SDK
    
  2. To your project's settings.gradle file, add the following content:

    def firebase_cpp_sdk_dir = System.getProperty('firebase_cpp_sdk.dir')
    
    gradle.ext.firebase_cpp_sdk_dir = "$firebase_cpp_sdk_dir"
    includeBuild "$firebase_cpp_sdk_dir"
    
  3. To your module (app-level) Gradle file—usually app/build.gradle— add the following content, which includes the library dependency for the Google Mobile Ads C++ SDK.

    android.defaultConfig.externalNativeBuild.cmake {
      arguments "-DFIREBASE_CPP_SDK_DIR=$gradle.firebase_cpp_sdk_dir"
    }
    
    # Add the dependency for the Google Mobile Ads C++ SDK
    apply from: "$gradle.firebase_cpp_sdk_dir/Android/firebase_dependencies.gradle"
    firebaseCpp.dependencies {
      gma
    }
    
  4. To your project's CMakeLists.txt file, add the following content.

    # Add Firebase libraries to the target using the function from the SDK.
    add_subdirectory(${FIREBASE_CPP_SDK_DIR} bin/ EXCLUDE_FROM_ALL)
    
    # Add the Google Mobile Ads C++ SDK.
    
    # The Firebase C++ library `firebase_app` is required,
    # and it must always be listed last.
    
    set(firebase_libs
      firebase_gma
      firebase_app
    )
    
    target_link_libraries(${target_name} "${firebase_libs}")
    
  5. Sync your app to ensure that all dependencies have the necessary versions.

iOS

The steps in this section are an example of how to add the Google Mobile Ads C++ SDK to your iOS project.

  1. Get CocoaPods version 1 or later by running:

    sudo gem install cocoapods --pre
    
  2. Add the Google Mobile Ads pod from the unzipped SDK.

    1. Create a Podfile if you don't already have one:

      cd APP_DIRECTORY
      pod init
      
    2. To your Podfile, add the pods for the Google Mobile Ads C++ SDK, the Google User Messaging Platform SDK, and the minimal Firebase core SDK (required by the GMA C++ SDK):

      pod 'Firebase/CoreOnly'
      pod 'Google-Mobile-Ads-SDK'
      pod 'GoogleUserMessagingPlatform'
      
    3. Install the pods, then open the .xcworkspace file in Xcode.

      pod install
      open APP.xcworkspace
      
    4. Add the following frameworks from the Firebase C++ SDK to the project:

      • xcframeworks/firebase.xcframework
      • xcframeworks/firebase_gma.xcframework

You're all set! Your C++ app is configured to use the Google Mobile Ads C++ SDK without any other Firebase services.

Configure your app's AdMob app ID

Android

Follow step 3 of Configure your app as described by the Mobile Ads SDK Android guide and then come back to this page.

iOS

Follow the Update your Info.plist step as described by the Mobile Ads SDK iOS guide and then come back to this page.

Initialize the Google Mobile Ads SDK

Before loading ads, have your app initialize the Google Mobile Ads C++ SDK by calling firebase::gma::Initialize() which initializes the SDK and completes a firebase::Future once initialization is complete (or after a 30-second timeout). This needs to be done only once, ideally at app launch.

Ads may be preloaded by the Google Mobile Ads C++ SDK or mediation partner SDKs upon calling Initialize(). If you need to obtain consent from users in the European Economic Area (EEA), set any request-specific flags (such as tag_for_child_directed_treatment or tag_for_under_age_of_consent), or otherwise take action before loading ads, ensure you do so by invoking firebase::gma::SetRequestConfiguration() before initializing the Google Mobile Ads C++ SDK. For more information see our Targeting guide.

Here's an example of how to call Initialize():

Android

// Initialize the Google Mobile Ads library
firebase::InitResult result;
Future<AdapterInitializationStatus> future =
  firebase::gma::Initialize(jni_env, j_activity, &result);

if (result != kInitResultSuccess) {
  // Initialization immediately failed, most likely due to a missing
  // dependency. Check the device logs for more information.
  return;
}

// Monitor the status of the future.
// See "Use a Future to monitor the completion status of a method call" below.
if (future.status() == firebase::kFutureStatusComplete &&
    future.error() == firebase::gma::kAdErrorCodeNone) {
  // Initialization completed.
} else {
  // Initialization on-going, or an error has occurred.
}

iOS

// Initialize the Google Mobile Ads library.
firebase::InitResult result;
Future<AdapterInitializationStatus> future =
  firebase::gma::Initialize(&result);

if (result != kInitResultSuccess) {
  // Initialization immediately failed, most likely due to a missing
  // dependency. Check the device logs for more information.
  return;
}

// Monitor the status of the future.
// See "Use a Future to monitor the completion status of a method call" below.
if (future.status() == firebase::kFutureStatusComplete &&
    future.error() == firebase::gma::kAdErrorCodeNone) {
  // Initialization completed.
} else {
  // Initialization on-going, or an error has occurred.
}

Use a Future to monitor the completion status of a method call

A Future provides you a way to determine the completion status of your asynchronous method calls.

For example, when your app calls firebase::gma::Initialize(), a new firebase::Future is created and returned. Your app can then poll the status() of the Future to determine when the initialization has completed. Once complete, your app can invoke result() to obtain the resulting AdapterInitializationStatus.

Methods that return a Future have a corresponding "last result" method that apps can use to retrieve the most recent Future for a given action. For example, firebase::gma::Initialize() has a corresponding method called firebase::gma::InitializeLastResult(), which returns a Future that your app can use to check the status of the last call to firebase::gma::Initialize().

If the status of the Future is complete and its error code is firebase::gma::kAdErrorCodeNone, then the operation has completed successfully.

You can also register callbacks to be invoked when a Future is completed. In some cases, the callback will be running in a different thread, so make sure your code is thread-safe. This code snippet uses a function pointer for the callback:

// Registers the OnCompletion callback. user_data is a pointer that is passed verbatim
// to the callback as a void*. This allows you to pass any custom data to the callback
// handler. In this case, the app has no data, so you must pass nullptr.
firebase::gma::InitializeLastResult().OnCompletion(OnCompletionCallback,
  /*user_data=*/nullptr);

// The OnCompletion callback function.
static void OnCompletionCallback(
  const firebase::Future<AdapterInitializationStatus>& future, void* user_data) {
  // Called when the Future is completed for the last call to firebase::gma::Initialize().
  // If the error code is firebase::gma::kAdErrorCodeNone,
  // then the SDK has been successfully initialized.
  if (future.error() == firebase::gma::kAdErrorCodeNone) {
    // success!
  } else {
    // failure.
  }
}

Select an ad format

The Google Mobile Ads C++ SDK is now imported and you're ready to implement an ad. AdMob offers a number of different ad formats, so you can choose the one that best fits your app's user experience.

Rectangular ads that appear at the top or bottom of the device screen. Banner ads 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.

Implement banner ads

Interstitial

Full-screen ads that cover the interface of an app until closed by the user. They're best used at natural pauses in the flow of an app's execution, such as between levels of a game or just after a task is completed.

Implement interstitial ads

Rewarded

Ads that reward users for watching short videos and interacting with playable ads and surveys. Used for monetizing free-to-play apps.

Implement rewarded ads