使用入门：在 C++ 项目中使用 AdMob

本快速入门指南适合想要使用 AdMob 通过由 Firebase 构建的应用变现的发布商和开发者。如果您不打算在应用中添加 Firebase，请参阅单独的 AdMob 指南。

了解搭配使用 AdMob、Firebase 和 Google Analytics（分析）的优势（如果您尚未了解）。

如果这是您首次依据本指南进行操作，我们建议您下载 Google 移动广告 C++ SDK 测试应用并按照说明操作。

准备工作

  • 如果您还没有 Firebase 项目和 Firebase 应用，请按照 Firebase 入门指南《将 Firebase 添加到您的 C++ 项目》进行操作。

  • 确保您的 Firebase 项目中启用了 Google Analytics（分析）：

    • 如果您要创建新的 Firebase 项目，请在项目创建过程中启用 Google Analytics（分析）。

    • 如果您已有 Firebase 项目，但未启用 Google Analytics（分析），可以从 >“项目设置”的集成标签页中启用 Google Analytics（分析）。

第 1 步：在 AdMob 帐号中设置应用

  1. 将您的应用的每个平台变体注册为 AdMob 应用。

    1. 登录或注册 AdMob 帐号。

    2. 向 AdMob 注册您的应用的每个平台变体。此步骤将创建一个具有唯一 AdMob 应用 ID 的 AdMob 应用，本指南稍后将用到此 ID。

    系统会要求您将移动广告 SDK 添加到您的应用中。如需详细了解如何添加，请参阅本指南的后面部分。

  2. 将您的每个 AdMob 应用与相应的 Firebase 应用相关联。

    这不是必须执行的步骤，但我们强烈建议您执行此操作。详细了解启用用户指标以及将 AdMob 应用关联到 Firebase 的好处。

    对于每个平台变体，请在您的 AdMob 帐号的应用信息中心内完成以下两个步骤：

    1. 启用用户指标，以允许 AdMob 处理特选分析数据并在您的 AdMob 帐号中显示。将您的 AdMob 应用关联到 Firebase，这也是一项必需设置。

    2. 将您的 AdMob 应用关联到您现有的 Firebase 项目和相应的 Firebase 应用。

      请务必输入您之前为 Firebase 应用输入的软件包名称 (Android) 或软件包 ID (iOS)。您可以在 > 项目设置的“您的应用”卡片中找到 Firebase 应用的软件包名称或软件包 ID。

第 2 步：将 AdMob 应用 ID 添加到您的应用中

Android

在您的应用的 AndroidManifest.xml 文件中，按下文所示添加 <meta-data> 标记，从而添加您的 AdMob 应用 ID。

<manifest>
    <application>
        <!-- Sample AdMob App ID: ca-app-pub-3940256099942544~3347511713 -->
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ADMOB_APP_ID"/>
    </application>
</manifest>

iOS

在应用的 Info.plist 文件中，添加一个 GADApplicationIdentifier 键，其值为字符串形式的 AdMob 应用 ID。

您可以通过编程方式进行此项更改：

<!-- Sample AdMob App ID: ca-app-pub-3940256099942544~1458002511 -->
<key>GADApplicationIdentifier</key>
<string>ADMOB_APP_ID</string>

您也可以在属性列表编辑器中进行修改：

属性列表编辑器

第 3 步：添加 Google 移动广告 SDK

由于 Google 移动广告 C++ SDK 位于 firebase::gma 命名空间中，因此请下载 Firebase C++ SDK，然后将其解压缩到您选择的目录中。

Firebase C++ SDK 并不局限于特定平台，但需要配置平台专用库。

Android

  1. 在项目的 gradle.properties 文件中，指定已解压缩的 SDK 的位置：

    systemProp.firebase_cpp_sdk.dir=FULL/PATH/TO/SDK

  2. 在项目的 settings.gradle 文件中，添加以下内容：

    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. 在您的模块（应用级）Gradle 文件（通常是 app/build.gradle）中添加以下内容，其中包含 Google 移动广告 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. 在项目的 CMakeLists.txt 文件中，添加以下内容。

    # 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. 同步您的应用，确保所有依赖项都具有所需的版本。

大功告成！您的 C++ 应用已配置为使用 Google 移动广告 C++ SDK。

iOS

本部分中的步骤说明了如何将 Google 移动广告 C++ SDK 添加到您的 iOS 项目中。

  1. 运行以下命令，获取 CocoaPods 1 或更高版本：

    sudo gem install cocoapods --pre

  2. 从已解压缩的 SDK 添加 Google 移动广告 Pod。

    1. 如果您没有 Podfile，请创建一个：

      cd YOUR_APP_DIRECTORY
pod init

    2. 将用于 Google 移动广告 C++ SDK 的 Pod 添加到您的 Podfile：

      pod 'Google-Mobile-Ads-SDK'

    3. 安装该 Pod，然后在 Xcode 中打开 .xcworkspace 文件。

      pod install
open YOUR_APP.xcworkspace

    4. 从 Firebase C++ SDK 将以下框架添加到项目中：

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

大功告成！您的 C++ 应用已配置为使用 Google 移动广告 C++ SDK。

第 4 步：初始化 Google 移动广告 SDK

在加载广告之前，请先调用 firebase::gma::Initialize() 来初始化移动广告 SDK。

此调用会返回在初始化结束后（或在 30 秒超时后）完成的 firebase::Future。应尽早调用此方法（最好在应用启动时调用），且仅应调用一次。

以下示例展示了如何调用 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.
}

使用 Future 监控方法调用的完成状态

Future 提供了一种方法来确定异步方法调用的完成状态。

例如，当您的应用调用 firebase::gma::Initialize() 时，系统会创建并返回一个新的 firebase::Future。然后，您的应用就可以轮询 Future 的 status()，以确定初始化是否已完成。初始化完成后，您的应用便可以调用 result() 来获取生成的 AdapterInitializationStatus。

返回 Future 的方法都有一个对应的“last result”（上次结果）方法，应用可以使用这一方法来获取给定操作的最新 Future。例如，firebase::gma::Initialize() 有一个名为 firebase::gma::InitializeLastResult() 的对应方法，该方法会返回一个 Future，您的应用可以用其来检查上次调用 firebase::gma::Initialize() 的状态。

如果 Future 的状态为已完成，且其错误代码为 firebase::gma::kAdErrorCodeNone，则表示操作成功完成。

您还可以注册当 Future 变成已完成状态时要调用的回调函数。在某些情况下，回调函数会在不同的线程中运行，因此请确保您的代码具有线程安全性。以下代码段使用了一个函数指针来实现回调：

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

第 5 步：选择要在您的应用中植入的广告格式

AdMob 提供多种不同的广告格式，您可以选择最适合应用用户体验的广告格式。点击相应广告格式对应的按钮，即可在 AdMob 文档中查看详细的植入说明。

横幅广告是在设备屏幕的顶部或底部展示的矩形广告

用户与应用互动时，横幅广告会停留在界面上，并且可在一段时间后自动刷新。如果您是刚开始接触移动广告的新手，横幅广告是您的绝佳选择。

植入横幅广告

插页式广告

插页式广告是全屏广告，它会覆盖整个应用界面，直到用户将其关闭

插页式广告最适合在应用执行流程中的自然暂停位置展示，例如游戏关卡之间或是用户刚完成一项任务之后。

植入插页式广告

激励广告

向观看短视频和与试玩广告及问卷调查互动的用户予以奖励的广告

激励广告（即“基于奖励”的广告）有助于通过免费游戏用户创收。

植入激励广告

其他相关主题

查看用户指标和分析数据

初始化后，移动广告 SDK 会自动开始记录您应用中的分析事件和用户属性。您无需向应用添加任何其他代码或植入任何广告即可查看这些数据。您可以在以下位置查看这些分析数据：

请注意，在对 ARPU 和 ARPPU 指标进行收入计算时，为了更好地表示这些指标，您可能需要添加名为 ecommerce_purchase 的分析自定义事件中的数据（了解如何操作）。

（可选）使用 Google Analytics（分析）和 Firebase 的更多功能

充分利用更多机会和功能，提高应用创收能力和用户互动度：