开始使用

本指南适用于希望在不使用 Firebase 的情况下，借助 AdMob 通过 C++ 应用创收的发布商。如果您计划在应用中添加 Firebase（或者正在考虑使用该功能），请改为参阅本指南的结合使用 AdMob 版本。

要展示广告并赚取收入，第一步是将 Google 移动广告 C++ SDK 集成到应用中。集成 SDK 后，您可以选择插页式广告或激励广告等广告格式，然后按照相应步骤进行实现。

Google 移动广告 C++ SDK 封装了 Google 移动广告 iOS SDK 和 Android SDK，并且仅适用于这两个平台。Google 移动广告 C++ SDK 使用 Firebase C++ 结构来支持异步操作，因此它位于 firebase::gma 命名空间中。

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

前提条件

Android

  • 使用 Android Studio 3.2 或更高版本
  • 确保应用的 build 文件使用以下值：
    • minSdkVersion 为 16 或更高版本
    • compileSdkVersion 为 28 或更高

iOS

  • 使用 Xcode 13 或更高版本
  • 定位到 iOS 10.0 或更高版本

在 AdMob 帐号中设置应用

完成以下步骤，将您的应用注册为 AdMob 应用：

  1. 登录或注册 AdMob 帐号。

  2. 在 AdMob 中注册您的应用。此步骤将创建一个具有唯一 AdMob 应用 ID 的 AdMob 应用，本指南稍后将用到此 ID。

安装 Google 移动广告 C++ SDK

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

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

Android

我们建议使用 CMake，但您可以在我们的常规 Firebase C++ SDK 入门指南中找到有关 ndk-build 的说明，将 libfirebase_app.a 和 libfirebase_gma.a 关联到您的应用。

  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. 同步应用以确保所有依赖项都具有必要的版本。

iOS

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

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

    sudo gem install cocoapods --pre

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

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

      cd APP_DIRECTORY
pod init

    2. 在 Podfile 中，添加用于 Google 移动广告 C++ SDK、Google User Messaging Platform SDK 和最低版本的 Firebase 核心 SDK（GMA C++ SDK 需要）的 Pod：

      pod 'Firebase/CoreOnly'
pod 'Google-Mobile-Ads-SDK'
pod 'GoogleUserMessagingPlatform'

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

      pod install
open APP.xcworkspace

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

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

您已准备就绪！您的 C++ 应用已配置为使用 Google 移动广告 C++ SDK，而不使用任何其他 Firebase 服务。

配置应用的 AdMob 应用 ID

Android

按照 Android 移动广告 SDK 指南中所述，按照配置您的应用的第 3 步操作，然后返回此页面。

iOS

按照移动广告 SDK iOS 指南中所述的方法更新您的 Info.plist，然后再返回此页面。

初始化 Google 移动广告 SDK

加载广告之前，请先调用 firebase::gma::Initialize()，以便让应用初始化 Google 移动广告 C++ SDK。该方法将初始化 SDK，并在初始化完成后（或在 30 秒超时后）完成 firebase::Future。此操作仅需执行一次，最好是在应用启动时执行。

在调用 Initialize() 时，Google 移动广告 C++ SDK 或中介合作伙伴 SDK 可能会预加载广告。如果您需要获得欧洲经济区 (EEA) 用户的同意，请设置任何专门用于特定请求的标记（例如 tag_for_child_directed_treatment 或 tag_for_under_age_of_consent），或者在加载广告之前采取其他措施，请确保在初始化 Google 移动广告 C++ SDK 之前调用 firebase::gma::SetRequestConfiguration() 来做到这一点。有关详情，请参阅我们的定位指南。

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

选择广告格式

Google 移动广告 C++ SDK 现已导入，您随时可以植入广告了。AdMob 提供了许多不同的广告格式，您可以根据您应用的用户体验选择最契合的一种。

横幅广告是在设备屏幕的顶部或底部展示的矩形广告。 用户与应用互动时，横幅广告会停留在屏幕上，并且可在一段时间后自动刷新。如果您是刚开始接触移动广告的新手，横幅广告是您的绝佳选择。

植入横幅广告

插页式广告

全屏广告，它会覆盖整个应用界面，直到用户将其关闭。 在应用执行流程的自然停顿点，例如游戏的不同关卡之间，或一项任务完成后，最适合投放这类广告。

植入插页式广告

已奖励

向观看短视频和与试玩广告及问卷调查互动的用户予以奖励的广告。用于通过免费游戏应用创收。

植入激励广告