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

建議使用 AdMob 的 iOS 和 Android SDK。


本快速入門指南適用於想使用 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，可以前往 >「專案設定」的「整合」分頁標籤啟用 Google Analytics。

    。

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

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

    1. 登入或註冊 AdMob 帳戶。

    2. 使用 AdMob 註冊應用程式的每個平台變體。這個步驟會建立 AdMob 應用程式，並產生專屬的 AdMob 應用程式 ID (本指南後續步驟會用到)。

    您將被要求將 Mobile Ads SDK 新增到您的應用程式中。本指南稍後將詳細介紹此任務。

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

    此步驟為可選步驟，但強烈建議執行。瞭解啟用使用者指標並將您的 AdMob 應用程式連結到 Firebase 的 好處。

    對於每個平台版本，請在您的 AdMob 帳戶的 Apps 控制面板中完成以下兩個步驟：

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

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

      請確保您輸入的套件名稱（Android）或 Bundle ID（iOS）與您為 Firebase 應用程式輸入的套件名稱或 Bundle ID 相同。您可以在 > 專案設定 的 您的應用程式 卡片中找到 Firebase 應用程式的套件名稱或 Bundle ID。

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

Android

將AdMob應用程式 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 行動廣告 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()：

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 文件中查看詳細的實施說明。

出現在裝置螢幕頂部或底部的矩形廣告

使用者操作應用程式時，橫幅廣告會持續停留在畫面上，並能定時自動更新內容。如果你是行動廣告新手，它們是一個很好的起點。

實施橫幅廣告

插頁式

完全覆蓋應用程式介面的全螢幕廣告，使用者需自行關閉

插頁式廣告最適合在應用程式運行流程的自然停頓處使用，例如遊戲關卡之間或任務完成後。

實施插頁式廣告

獎勵廣告

透過獎勵用戶觀看短影片、與可玩廣告和調查互動來吸引用戶投放的廣告

獎勵廣告 (或「以獎勵為基礎」的廣告) 有助於透過免費遊戲使用者營利。

實施激勵廣告

其他感興趣的主題

查看用戶指標和分析數據

初始化完成後，Mobile Ads SDK 會自動開始記錄來自您應用的分析數據，包括 事件 和 使用者屬性。您無需在應用程式中添加任何額外程式碼或投放任何廣告，即可查看這些資料。您可以在這裡查看這些分析數據：

請注意，為了更好地表示 ARPU 和 ARPPU 指標，您可能需要將名為 ecommerce_purchase 的分析 custom 事件的資料包含在這些指標的收入計算中 (瞭解如何)。

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

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

  • 新增並使用 Firebase SDK 以進行 Google Analytics

    欲瞭解更多信息，請訪問指南。使用Google Analytics以及 FirebaseAdMob應用。

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

    在新增 Google Analytics 的 Firebase SDK 後，可以使用其他 Firebase 產品來優化應用程式中的廣告。

    • Remote Config 可讓您直接變更應用程式行為和外觀 (不用發布應用程式更新)，而且不限每日活躍使用者人數，完全免費。

    • A/B Testing 可讓您測試應用程式的 UI、功能或互動活動的更改，以瞭解這些更改是否會對關鍵指標（如收入和留存率）產生影響，然後再廣泛推出這些變更。