在 C++ 專案中開始使用 AdMob

步驟 1：在 AdMob 帳戶中設定應用程式

1. 將應用程式的每個平台變化版本註冊為 AdMob 應用程式。

   1. 登入或註冊 AdMob 帳戶。

   2. 使用 AdMob 註冊應用程式的每個平台變化版本。這個步驟會建立 AdMob 應用程式，並提供您稍後在本指南中需要的專屬 AdMob 應用程式 ID。

   系統會要求您將 Mobile Ads SDK 新增至應用程式。請參閱本指南稍後的部分，瞭解這項工作的詳細操作說明。

2. 將每個 AdMob 應用程式連結至對應的 Firebase 應用程式。

   這是選用步驟，但強烈建議執行。進一步瞭解啟用使用者指標和將 AdMob 應用程式連結至 Firebase 的優點。

   針對每個平台變化版本，請在 AdMob 帳戶的「應用程式」資訊主頁中完成下列兩個步驟：

   1. 啟用使用者指標，讓 AdMob 在您的 AdMob 帳戶中處理及���������選��������分析資料。您也必須設定此選項，才能將 AdMob 應用程式連結至 Firebase。

   2. 將 AdMob 應用程式連結至現有的 Firebase 專案和對應的 Firebase 應用程式。

      請務必輸入與 Firebase 應用程式相同的套件名稱 (Android) 或繫結 ID (iOS)。如要查看 Firebase 應用程式的套件名稱或繫結 ID，請依序前往 settings > 專案設定 的「Your apps」資訊卡。

步驟 2：將 AdMob App ID 新增至應用程式

Android

如要將 AdMob App ID 新增至應用程式的 AndroidManifest.xml 檔案，請新增 <meta-data> 標記，如下所示。

<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 Mobile Ads SDK

由於 Google Mobile Ads 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 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. 在專案的 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 Mobile Ads C++ SDK。

iOS

本節的步驟示範如何將 Google Mobile Ads C++ SDK 新增至 iOS 專案。

1. 如要取得 CocoaPods 1 以上版本，請執行以下指令：

   sudo gem install cocoapods --pre

2. 從已解壓縮的 SDK 新增 Google Mobile Ads Pod。

   1. 如果你沒有 Podfile，請先建立 Podfile：

      cd YOUR_APP_DIRECTORY
      pod init

   2. 在 Podfile 中加入 Google Mobile Ads 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 Mobile Ads C++ SDK。

步驟 4：初始化 Google Mobile Ads SDK

在載入廣告之前，請透過呼叫 firebase::gma::Initialize() 初始化 Mobile Ads 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 說明文件中查看詳細的導入操作說明。

橫幅

這類矩形廣告會顯示在裝置畫面頂端或底部

使用者與應用程式互動時，橫幅廣告會停留在畫面上，且經過一段時間後會自動重新整理。如果您是行動廣告新手，不妨從這裡開始。

插頁式

全螢幕廣告會覆蓋應用程式的介面，直到使用者關閉為止

插頁式廣告最適合用於應用程式執行流程中的自然暫停時間，例如遊戲關卡之間，或任務完成後。

獎勵廣告

在使用者看完短片、與可試玩廣告及問卷調查互動後提供獎勵的廣告

獎勵廣告 (或稱「獎勵制廣告」) 可協助您透過免費遊戲玩家營利。

導入獎勵廣告

其他感興趣的主題

查看使用者指標和數據分析資料

初始化完成後，Mobile Ads SDK 就會自動開始記錄應用程式中的數據分析事件和使用者屬性。您無須在應用程式中新增任何額外程式碼或導入廣告，即可查看這類資料。您可以透過下列方式查看這些數據分析資料：

• 在 AdMob 帳戶的「使用者指標」資訊卡 (首頁或「應用程式」資訊主頁) 中，您可以查看從收集到的分析資料衍生而來的使用者指標，例如平均工作階段時間、ARPU 和回訪率。

• 在 Firebase 主控台的 Analytics 資訊主頁中，您可以查看匯總統計資料和重點指標摘要。如果您為 Google Analytics 新增 Firebase SDK，也可以在 Firebase 控制台標示廣告活動的轉換，並建立自訂目標對象。

請注意，為更準確呈現ARPU 和 ARPPU 指標，您可能需要在這些指標的收益計算中納入名為 ecommerce_purchase 的 Analytics 自訂 事件資料 (瞭解如何操作)。

(選用) 使用 Google Analytics 和 Firebase 的更多功能

善用更多商機和功能，提升應用程式營利成效和使用者參與度：

• 為 Google Analytics 新增及使用 Firebase SDK

  • 在應用程式中實作自訂事件記錄功能。

  • 為自訂廣告活動標示轉換。

  • 在ARPU 和 ARPPU 指標的收益計算中納入 ecommerce_purchase 事件資料。

  如需更多資訊，請參閱搭配 AdMob 應用程式使用 Google Analytics 和 Firebase 的指南。

• 在應用程式中使用其他 Firebase 產品

  新增 Google Analytics 專用 Firebase SDK 後，請使用其他 Firebase 產品來改善應用程式中的廣告。

  • Remote Config 可讓您免費變更應用程式的行為和外觀，且無須發布應用程式更新，適用於無限量的每日活躍使用者。

  • A/B Testing 可讓您測試對應用程式使用者介面、功能或參與度廣告活動所做的變更，以在廣泛實作之前，瞭解變更是否確實能對關鍵指標 (例如收益和留存率) 發揮效用。