Check out what’s new from Firebase at Google I/O 2022. Learn more

開始使用

您可以使用 AdMob 在您的 C++ 應用中展示廣告。本指南向您展示如何與 Firebase 集成並與 Google 移動廣告 SDK 交互。

如果這是您第一次閱讀本指南，建議您下載並使用AdMob 測試應用進行操作。

與 Firebase 集成

  1. 完成iOS設置或Android 設置部分中的步驟，將 AdMob 和 Firebase 添加到您的 C++ 應用。

  2. 在應用的 C++ 代碼中包含以下標頭：

    #include "firebase/admob.h"
#include "firebase/admob/types.h"
#include "firebase/app.h"
#include "firebase/future.h"

  3. 將以下代碼添加到您應用的 C++ 代碼中，以使用您的 AdMob 應用 ID 初始化 AdMob 庫（此代碼應在創建橫幅視圖或插頁式廣告之前執行）：

    #if defined(__ANDROID__)
// Create the Firebase app.
firebase::App* app =
    firebase::App::Create(firebase::AppOptions(),
                          your_jni_env,
                          your_android_activity);

// Your Android AdMob app ID.
const char* kAdMobAppID = "ca-app-pub-XXXXXXXXXXXXXXXX~NNNNNNNNNN";
#else
// Create the Firebase app.
firebase::App* app =
    firebase::App::Create(firebase::AppOptions());

// Your iOS AdMob app ID.
const char* kAdMobAppID = "ca-app-pub-XXXXXXXXXXXXXXXX~NNNNNNNNNN";
#endif  // __ANDROID__

// Initialize the AdMob library with your AdMob app ID.
firebase::admob::Initialize(*app, kAdMobAppID);

與 Google 移動廣告 SDK 交互

設置廣告單元 ID

在編寫 iOS 和 Android 都支持的 C++ 代碼時，您可能需要使用預處理器指令來定義只應在特定操作系統上編譯的代碼。要在 iOS 和 Android 上顯示橫幅廣告和插頁式廣告，建議您為每個操作系統和每個獨特的廣告展示位置創建一個新的廣告單元 ID。以下廣告單元 ID 是為 iOS 和 Android 創建的，並配置為始終投放測試廣告：

#if defined(__ANDROID__)
// Android ad unit IDs
const char* kBannerAdUnit = "ca-app-pub-3940256099942544/6300978111";
const char* kInterstitialAdUnit = "ca-app-pub-3940256099942544/1033173712";
#else
// iOS ad unit IDs
const char* kBannerAdUnit = "ca-app-pub-3940256099942544/2934735716";
const char* kInterstitialAdUnit = "ca-app-pub-3940256099942544/4411468910";
#endif

設置橫幅視圖

將以下標頭添加到您應用的 C++ 代碼中：

#include "firebase/admob/banner_view.h"

聲明並實例化一個BannerView對象：

firebase::admob::BannerView* banner_view;
banner_view = new firebase::admob::BannerView();

創建一個AdSize並初始化橫幅視圖：

firebase::admob::AdSize ad_size;
ad_size.ad_size_type = firebase::admob::kAdSizeStandard;
ad_size.width = 320;
ad_size.height = 50;
// my_ad_parent is a reference to an iOS UIView or an Android Activity.
// This is the parent UIView or Activity of the banner view.
banner_view->Initialize(static_cast<firebase::admob::AdParent>(my_ad_parent), kBannerAdUnit, ad_size);

設置插頁式廣告

將以下標頭添加到您應用的 C++ 代碼中：

#include "firebase/admob/interstitial_ad.h"

聲明並實例化一個InterstitialAd對象：

firebase::admob::InterstitialAd* interstitial_ad;
interstitial_ad = new firebase::admob::InterstitialAd();

初始化插頁式廣告：

// my_ad_parent is a reference to an iOS UIView or an Android Activity.
// This is the parent UIView or Activity of the interstitial ad.
interstitial_ad->Initialize(static_cast<firebase::admob::AdParent>(my_ad_parent), kInterstitialAdUnit);

創建 AdMob 廣告請求

AdMob 庫允許您為廣告請求提供自定義定位信息。這是通過設置AdRequest結構的成員來完成的。然後將該結構傳遞給BannerView::LoadAd()或InterstitialAd::LoadAd()方法。

有關定位和自定義廣告請求的一般信息，請查看我們的iOS和Android定位指南。

這是BannerView和InterstitialAd用來發出廣告請求的AdRequest結構：

struct AdRequest {
  const char **test_device_ids;
  unsigned int test_device_id_count;
  const char **keywords;
  unsigned int keyword_count;
  const KeyValuePair *extras;
  unsigned int extras_count;
  int birthday_day;
  int birthday_month;
  int birthday_year;
  Gender gender;
  ChildDirectedTreatmentState tagged_for_child_directed_treatment;
};

聲明並初始化AdRequest結構：

// Initialize all the AdRequest struct member values to zero.
firebase::admob::AdRequest my_ad_request = {};

以下代碼設置AdRequest結構的成員值以向廣告請求添加定位信息：

// If the app is aware of the user's gender, it can be added to the
// targeting information. Otherwise, "unknown" should be used.
my_ad_request.gender = firebase::admob::kGenderUnknown;

// The user's birthday, if known. Note that months are indexed from one.
my_ad_request.birthday_day = 10;
my_ad_request.birthday_month = 11;
my_ad_request.birthday_year = 1976;

// Additional keywords to be used in targeting.
static const char* kKeywords[] = {"AdMob", "C++", "Fun"};
my_ad_request.keyword_count = sizeof(kKeywords) / sizeof(kKeywords[0]);
my_ad_request.keywords = kKeywords;

// "Extra" key value pairs can be added to the request as well.
static const firebase::admob::KeyValuePair kRequestExtras[] = {
    {"the_name_of_an_extra", "the_value_for_that_extra"}};
my_ad_request.extras_count = sizeof(kRequestExtras) / sizeof(kRequestExtras[0]);
my_ad_request.extras = kRequestExtras;

// Register the device IDs associated with any devices that will be used to
// test your app. Below are sample test device IDs used for making the ad request.
static const char* kTestDeviceIDs[] =
    {"2077ef9a63d2b398840261c8221a0c9b",
     "098fe087d987c9a878965454a65654d7"};
my_ad_request.test_device_id_count =
    sizeof(kTestDeviceIDs) / sizeof(kTestDeviceIDs[0]);
my_ad_request.test_device_ids = kTestDeviceIDs;

將AdRequest結構傳遞給BannerView::LoadAd()和Interstitial::LoadAd()方法：

banner_view->LoadAd(my_ad_request);
interstitial_ad->LoadAd(my_ad_request);

Note: A single `AdRequest` struct can be reused for multiple calls.

使用 Futures 監控方法調用的完成狀態

Futures 為您提供了一種方法來確定您之前的BannerView或InterstitialAd方法調用的完成狀態。例如，當調用InterstitialAd::LoadAd()方法時，會創建並返回一個新的 Future。應用程序可以輪詢 Future 的狀態以確定廣告何時加載。 Future 完成後，插頁式廣告就可以在您的應用程序的下一個自然停止點展示。

BannerView和InterstitialAd類中的大多數方法都有一個相應的“最後結果”方法，應用程序可以使用該方法來檢索給定操作的最新 Future。例如， InterstitialAd::LoadAd()方法有一個相應的方法，稱為InterstitialAd::LoadAdLastResult() 。它返回一個 Future，可用於檢查最後一次調用InterstitialAd::LoadAd()方法的狀態。

類似地，應用程序可以使用BannerView::InitializeLastResult()方法來獲取表示上次調用BannerView::Initialize()方法的狀態（和錯誤代碼，如果有的話）的 Future。如果它的狀態是完整的並且它的錯誤代碼是firebase::admob::kAdMobErrorNone ，那麼你就可以通過調用BannerView::Show()方法使橫幅視圖可見：

if (banner_view->InitializeLastResult().status() ==
    firebase::kFutureStatusComplete &&
    banner_view->InitializeLastResult().error() ==
    firebase::admob::kAdMobErrorNone) {
  banner_view->Show();
}

一旦 Future 的最後一次調用BannerView::Show()方法的狀態完成，那麼您就可以將廣告加載到橫幅視圖中了：

if (banner_view->ShowLastResult().status() ==
    firebase::kFutureStatusComplete &&
    banner_view->ShowLastResult().error() ==
    firebase::admob::kAdMobErrorNone) {
  banner_view->LoadAd(my_ad_request);
}

對於插頁式廣告，使用InterstitialAd::InitializeLastResult()方法獲取表示最後一次調用InterstitialAd::Initialize()方法的狀態（和錯誤代碼，如果有）的 Future。如果其狀態為已完成且其錯誤代碼為firebase::admob::kAdMobErrorNone ，則您已準備好加載插頁式廣告：

if (interstitial_ad->InitializeLastResult().status() ==
    firebase::kFutureStatusComplete &&
    interstitial_ad->InitializeLastResult().error() ==
    firebase::admob::kAdMobErrorNone) {
  interstitial_ad->LoadAd(my_ad_request);
}

完成對InterstitialAd::LoadAd()方法的最後一次調用的 Future 狀態後，您就可以在應用程序的下一個自然停止點顯示插頁式廣告：

if (interstitial_ad->LoadAdLastResult().status() ==
    firebase::kFutureStatusComplete &&
    interstitial_ad->LoadAdLastResult().error() ==
    firebase::admob::kAdMobErrorNone) {
  interstitial_ad->Show();
}

您還可以註冊回調以在 Future 完成時調用。此代碼片段使用回調函數指針：

// Initialize the interstitial ad.
interstitial_ad->Initialize(static_cast<firebase::admob::AdParent>(my_ad_parent), kInterstitialAdUnit);

// Registers the OnCompletion callback. user_data is a pointer that is passed verbatim
// to the callback as a void*. In this example, we pass the interstitial ad object to be
// used in the OnCompletionCallback function.
interstitial_ad->InitializeLastResult().OnCompletion(OnCompletionCallback, interstitial_ad /*user_data*/);

// The OnCompletion callback function.
static void OnCompletionCallback(const firebase::Future<void>& future, void* user_data) {
  // Called when the Future is completed for the last call to the InterstitialAd::Initialize()
  // method. If the error code is firebase::admob::kAdMobErrorNone, then you're ready to
  // load the interstitial ad.
  firebase::admob::InterstitialAd *interstitial_ad = static_cast<firebase::admob::InterstitialAd*>(user_data);
  if (future.error() == firebase::admob::kAdMobErrorNone) {
    interstitial_ad->LoadAd(my_ad_request);
  }
}

使用監聽器接收廣告生命週期事件的通知

AdMob 提供了一個抽象的BannerView::Listener類，您可以擴展該類並將其傳遞給BannerView::SetListener()方法，以便在橫幅視圖的呈現狀態和邊界框發生更改時收到通知。類似的抽象InterstitialAd::Listener類也提供給可擴展的插頁式廣告，以便在插頁式廣告的展示狀態更改時收到通知。

下面是一個擴展BannerView::Listener類的示例實現（類似的實現可用於插頁式廣告）：

class ExampleBannerViewListener
    : public firebase::admob::BannerView::Listener {
public:
  ExampleBannerViewListener() {}

  void OnPresentationStateChanged(
      firebase::admob::BannerView* banner_view,
      firebase::admob::BannerView::PresentationState state) override {
    // This method gets called when the banner view's presentation
    // state changes.
  }

  void OnBoundingBoxChanged(
      firebase::admob::BannerView* banner_view,
      firebase::admob::BoundingBox box) override {
    // This method gets called when the banner view's bounding box
    // changes.
  }
};

下一步是什麼

了解如何使用 AdMob通過您的應用獲利，並確保將本指南中使用的測試廣告單元 ID 替換為您自己的廣告單元 ID。