在您的 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（分析），您可以從您的 Firebase 專案的「整合」標籤中啟用 Google Analytics。 settings >項目設定。

步驟 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 應用程式。

      確保您輸入的套件名稱 (Android) 或捆綁包 ID (iOS) 與您為 Firebase 應用程式輸入的套件名稱相同。在您的 Firebase 應用程式的「您的應用程式」卡中尋找您的 Firebase 應用程式的套件名稱或捆綁包 ID settings >項目設定。

步驟 2：將您的 AdMob 應用程式 ID 新增至您的應用程式中

安卓

透過新增<meta-data>標記，將您的AdMob 應用程式 ID新增至已套用的AndroidManifest.xml檔案中，如下所示。

<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 不特定於平台，但它確實需要特定於平台的程式庫配置。

安卓

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 行動廣告窗格。

   1. 如果您還沒有 Podfile，請建立一個：

      cd YOUR_APP_DIRECTORY
      pod init

   2. 在您的 Podfile 中，新增 Google 行動廣告 C++ SDK 的 Pod：

      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。

此呼叫傳回一個firebase::Future ，一旦初始化完成（或 30 秒逾時後），該呼叫就會完成。僅呼叫此方法一次，並且盡可能早，最好是在應用程式啟動時呼叫。

以下是如何呼叫Initialize()的範例：

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

// 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的方法有一個對應的「最後結果」方法，應用程式可以使用該方法來擷取給定操作的最新Future 。例如， firebase::gma::Initialize()有一個名為firebase::gma::InitializeLastResult()的對應方法，它傳回一個Future ，您的應用程式可以使用它來檢查上次呼叫firebase::gma::Initialize() 。

如果Future的狀態為 Complete 且其錯誤代碼為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 文件中的詳細實施說明。

橫幅

顯示在裝置螢幕頂部或底部的矩形廣告

當用戶與應用程式互動時，橫幅廣告會保留在螢幕上，並且可以在一段時間後自動刷新。如果您是行動廣告新手，那麼它們是一個很好的起點。