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

本快速入門指南適用於想要透過 AdMob 使用以 Firebase 建構的應用程式營利的發布商和開發人員。如果您不打算將 Firebase 加入應用程式，請改為參閱獨立式 AdMob 指南。

如果您尚未準備好，不妨進一步瞭解搭配使用 AdMob、Firebase 和 Google Analytics (分析) 的所有優點。

如果這是您第一次閱讀本指南，建議您下載並使用 Google Mobile Ads C++ SDK 測試應用程式。

事前準備

  • 如果您尚未擁有 Firebase 專案和 Firebase 應用程式，請按照 Firebase 入門指南的說明：將 Firebase 新增至 C++ 專案。

  • 請確認您的 Firebase 專案已啟用 Google Analytics (分析)：

    • 如要建立新的 Firebase 專案，請在專案建立工作流程中啟用 Google Analytics (分析)。

    • 如果現有的 Firebase 專案尚未啟用 Google Analytics (分析)，您可以前往 >「Project settings」(專案設定) 的「Integrations」(整合) 分頁啟用 Google Analytics (分析)。

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

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

    1. 登入或註冊 AdMob 帳戶。

    2. 透過 AdMob 註冊您應用程式的每個平台變化版本。這個步驟會使用專屬的 AdMob 應用程式 ID 建立 AdMob 應用程式，本指南稍後會用到。

    系統會要求您在應用程式中加入 Mobile Ads SDK。如需這項工作的詳細操作說明，請參閱本指南。

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

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

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

    1. 啟用使用者指標，以便 AdMob 在您的 AdMob 帳戶中處理及顯示精選分析資料。這也是將 AdMob 應用程式連結至 Firebase 的必要設定。

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

      請務必輸入您為 Firebase 應用程式輸入的套件名稱 (Android) 或軟體包 ID (iOS)。您可以前往 >「Project settings」，在「Your apps」資訊卡中找到 Firebase 應用程式的套件名稱或軟體包 ID。

步驟 2：在應用程式中加入 AdMob 應用程式 ID

Android

加入 <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 檔案中，加入內含 AdMob 應用程式 ID 字串值的 GADApplicationIdentifier 鍵。

您可以透過程式輔助方式進行這項變更：

<!-- 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 廣告連播。

    1. 如果您尚未建立 Podfile，請建立一個：

      cd YOUR_APP_DIRECTORY
pod init

    2. 請在 Podfile 中新增 Google Mobile Ads C++ SDK 的廣告連播：

      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。

這項呼叫會傳回在初始化完成 (或逾時後 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 的方法具有對應的「最終結果」方法，應用程式可用來擷取指定動作的最新 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 說明文件中查看詳細的導入操作說明。

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

橫幅廣告會在使用者與應用程式互動時持續顯示在畫面上，並在一段時間後自動重新整理。如果你是行動廣告新手，建議從這裡著手。

導入橫幅廣告

插頁式

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

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

導入插頁式廣告

獎勵廣告

廣告會在使用者觀看短片、與可試玩廣告及問卷調查互動時發送獎勵

獎勵廣告 (又稱「獎勵型」) 廣告可透過免費遊戲使用者營利。

導入獎勵廣告

其他感興趣的主題

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

初始化完成後，Mobile Ads SDK 會自動開始記錄應用程式中的數據分析事件和使用者屬性。您不需要在應用程式中新增任何額外程式碼或導入任何廣告，就能查看這些資料。您可以在這裡查看這項數據分析資料：

請注意，為了更妥善地呈現 ARPU 和 ARPPU 指標，您可能需要將名為 ecommerce_purchase 的數據分析自訂事件資料納入這些指標的收益計算中 (瞭解詳情)。

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

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