開始使用

本指南適用於想要以 C++ 應用程式 (而非 Firebase) 透過 C++ 應用程式營利的發布商。如果您打算在應用程式中加入 Firebase (或考慮使用),請改為參閱本指南的搭配 Firebase 使用 AdMob 版本。

將 Google Mobile Ads C++ SDK 整合至應用程式,是顯示廣告並賺取收益的第一步。整合 SDK 後,您可以選擇插頁式廣告或獎勵廣告等廣告格式,然後按照步驟導入。

Google Mobile Ads C++ SDK 會包裝 Google Mobile Ads iOS 和 Android SDK,且僅適用於這些平台。Google Mobile Ads C++ SDK 使用 Firebase C++ 建構來支援非同步作業,因此位於 firebase::gma 命名空間中。

如果您是第一次閱讀本指南,建議您下載並使用 Google Mobile Ads C++ 測試版應用程式進行操作。

必要條件

Android

  • 使用 Android Studio 3.2 以上版本
  • 請確認應用程式的版本檔案使用下列值:
    • minSdkVersion 16 以上
    • compileSdkVersion 28 以上

iOS

  • 使用 Xcode 13 以上版本
  • 指定 iOS 10.0 以上版本

在 AdMob 帳戶中設定應用程式

完成下列步驟,即可將應用程式註冊為 AdMob 應用程式:

  1. 登入註冊 AdMob 帳戶。

  2. 向 AdMob 註冊應用程式。這個步驟會使用專屬 AdMob 應用程式 ID 建立 AdMob 應用程式,本指南稍後需要使用此 ID。

安裝 Google Mobile Ads C++ SDK

由於 Google Mobile Ads C++ SDK 位於 firebase::gma 命名空間中,請下載 Firebase C++ SDK,然後將其解壓縮至自選的目錄。

Firebase C++ SDK 並非特定平台,但需要特定平台的程式庫設定。

Android

我們建議您使用 CMake。不過,您可以在我們一般的 Firebase C++ SDK 入門指南libfirebase_app.alibfirebase_gma.a 連結至應用程式,查看 ndk-build 的操作說明。

  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. 請同步處理應用程式,確保所有依附元件都有必要版本。

iOS

本節提供範例,說明如何將 Google Mobile Ads C++ SDK 加進 iOS 專案。

  1. 執行下列指令,取得 CocoaPods 1 以上版本:

    sudo gem install cocoapods --pre
    
  2. 從已壓縮的 SDK 中加入 Google Mobile Ads Pod。

    1. 如果您尚未建立 Podfile,請建立一個:

      cd APP_DIRECTORY
      pod init
      
    2. 如果您的 Podfile,請新增 Google Mobile Ads 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 Mobile Ads C++ SDK,而不使用其他 Firebase 服務。

設定應用程式的 AdMob 應用程式 ID

Android

按照 Mobile Ads SDK Android 指南的說明,按照設定應用程式的步驟 3 操作,再返回本頁面。

iOS

按照 Mobile Ads SDK iOS 指南所述,按照「更新 Info.plist」步驟操作,然後返回本頁面。

初始化 Google Mobile Ads SDK

載入廣告前,請呼叫 firebase::gma::Initialize() 來初始化 Google Mobile Ads C++ SDK,此程序會在初始化完成後 (或 30 秒後) 完成 firebase::Future。此操作只需執行一次,最好在應用程式啟動時執行。

在呼叫 Initialize() 時,Google Mobile Ads C++ SDK 或中介服務合作夥伴 SDK 可能會預先載入廣告。如果您需要取得歐洲經濟區 (EEA) 使用者的同意聲明,請設定任何要求專屬標記 (例如 tag_for_child_directed_treatmenttag_for_under_age_of_consent),或是在載入廣告前採取行動,請務必在初始化 Google Mobile Ads 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 並傳回。接著,應用程式就可以輪詢 Futurestatus(),判斷初始化何時完成。完成後,應用程式即可叫用 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.
  }
}

選取廣告格式

您現在可以匯入 Google Mobile Ads C++ SDK,也可以導入廣告。AdMob 提供多種廣告格式,您可挑選最適合應用程式使用者體驗的廣告格式。

顯示在裝置螢幕頂端或底部的矩形廣告。 使用者與應用程式互動時,橫幅廣告會停留在畫面上,且會在一段時間後自動重新整理。如果您是第一次使用行動廣告 不妨從這裡著手

導入橫幅廣告

插頁式

全螢幕廣告,會蓋住應用程式介面,直到使用者關閉為止。 最適合用於應用程式執行流程中的自然暫停點,例如遊戲關卡之間或剛完成任務後。

導入插頁式廣告

已獲得獎勵

獎勵使用者觀看短片並與可試玩廣告和問卷調查互動的廣告。用於透過免費應用程式營利。

導入獎勵廣告