本頁面由 Cloud Translation API 翻譯而成。

改用新版 Google Mobile Ads C++ SDK

Firebase C++ SDK 9.1.0 版推出後，Google Mobile Ads C++ SDK 也隨之問世。

Google 行動廣告 C++ SDK 是一個新的 API 介面，它包含了 2021 年和 2022 年對適用於 iOS 和 Android 的 Firebase AdMob C++ SDK 所做的重大突破性更改，包括刪除已棄用的 API，以及使用全螢幕廣告類型時的新流程。

舊版 Firebase AdMob C++ SDK (firebase::admob) 已標示為已淘汰，未來不會再收到任何更新或錯誤修正。

在 Firebase AdMob C++ SDK 淘汰期間，新的 Google Mobile Ads C++ SDK (firebase::gma) 和舊的 Firebase AdMob C++ SDK (firebase::admob) 都會保留在 Firebase C++ SDK 的建構封存檔中。

移除舊版 API

下列 API 已從 Google Mobile Ads C++ SDK 中完全移除。

`RewardedVideoAd`

AdMob 的 RewardedVideoAd 命名空間已由 RewardedAd 類別取代。RewardedAd 的行為與 InterstitialAd 類似，但包含額外的 RewardedAdListener，可接收項目獎勵通知。

`NativeExpressAds`

AdMob 的 NativeExpressAd 已在各個 Firebase AdMob C++ SDK 中標示為已淘汰。因此，新版 Google Mobile Ads C++ SDK 不包含 NativeExpressAd。

SDK 命名空間變更

SDK 已遷移至新的命名空間，且具有新的目錄結構：

命名空間 `firebase::gma`

新版 Google Mobile Ads C++ SDK 的來源位於 firebase::gma 命名空間。舊版 firebase::admob 命名空間已淘汰，Firebase AdMob C++ SDK 也是如此。

目錄結構

標頭檔案已移至建構封存檔內的新目錄：

已淘汰的 Firebase AdMob C++ SDK	全新 Google Mobile Ads C++ SDK
`include/firebase/admob`	`include/firebase/gma`

程式庫

Firebase AdMob C++ SDK 會以靜態程式庫的形式提供，位於 Firebase C++ SDK 建構封存檔中：

iOS

已淘汰的 Firebase AdMob C++ SDK	全新 Google Mobile Ads C++ SDK
`firebase_admob.xcframework`	`firebase_gma.xcframework`

Android

已淘汰的 Firebase AdMob C++ SDK	全新 Google Mobile Ads C++ SDK
`libfirebase_admob.a`	`libfirebase_gma.a`

類別、列舉和結構體遷移作業

下表列出已變更或移除的特定類別、列舉和結構體。以下是重點摘要：

BannerView 已重新命名為 AdView。
已移除「NativeAdExpressView」。
RewardedVideo 命名空間會替換為 RewardedAd 類別。
PresentationState 列舉和監聽器已移除，並替換為 AdListener 和 FullScreenContent 監聽器。
系統會移除下列參數，因為這些參數是 AdRequests 中的單一廣告設定參數：
- 測試裝置 ID 的設定
- 根據年齡指定廣告
現在可以在 RequestConfiguration 中設定這些參數，這項全域設定會影響後續所有廣告載入作業。

已淘汰 `firebase::admob namespace`	新`firebase::gma namespace`
`AdSizeType` (enum)	`AdSize::Type` (enum)
`BannerView`	`AdView`
`BannerView::Listener`	`AdListener` `AdViewBoundingBoxListener` `PaidEventListener`
`BannerView::Position`	`AdView::Position`
`BannerView::PresentationState`	已移除
`ChildDirectedTreatmentState`	`RequestConfiguration::TagForChildDirectedTreatment`
`Gender` (enum)	已移除
`InterstitialAd::Listener`	`FullScreenContentListener` `PaidEventListener`
`KeyValuePair`	已移除
`NativeExpressAdView`	已移除
`PollableRewardListener`	已移除
`RewardItem`	`AdReward`
`RewardedVideoAd` (命名空間)	`RewardedAd` (類別)
`RewardedVideoAd::Listener`	`FullScreenContentListener` `PaidEventListener` `UserEarnedRewardListener`
`AdMobError` (enum)	`AdErrorCode` (enum)
`RewardItem`	`AdReward`

初始化 SDK

每個 Google Mobile Ads C++ SDK 初始化函式都會立即傳回兩個狀態指標：

選用的 out 參數會傳達初始化程序開始前是否發生依附元件錯誤。
傳回參數是 firebase::Future 的參照。Future 包含裝置上中介服務介面卡的非同步初始化結果。

雖然在初始化函式傳回後，即可呼叫 Google Mobile Ads C++ SDK 來載入 AdMob 放送的廣告，但其他廣告聯播網必須等到對應的中介服務介面卡完全初始化後，才會放送廣告。這項程序會以非同步方式執行。因此，如果您在應用程式中使用廣告中介服務，建議您等待 Future 解決問題，再嘗試載入任何廣告。

之前

firebase::App* app = ::firebase::App::Create();
firebase::InitResult result = firebase::admob::Initialize(*app, kAdMobAppID);

if (result != kInitResultSuccess) {
  // Initialization immediately failed, most likely due to a missing dependency.
  // Check the device logs for more information.
  return;
}

晚於

using firebase::App;
using firebase::Future;
using firebase::gma::AdapterInitializationStatus;

App* app = ::firebase::App::Create();
firebase::InitResult result;
Future<AdapterInitializationStatus> future =
  firebase::gma::Initialize(*app, &result);

if (result != kInitResultSuccess) {
  // Initialization immediately failed, most likely due to a missing dependency.
  // Check the device logs for more information.
  return;
}

// Poll the future to wait for its completion either in this
// thread, or as part of your game loop by calling
// firebase::gma::InitializeLastResult();
while (future.status() == firebase::kFutureStatusPending) {
  // Initialization on-going, continue to wait.
}

// future.status() is either kFutureStatusComplete or there’s an error

if (future.status() == firebase::kFutureStatusComplete &&
     future.error() == firebase::gma::AdErrorCodeNone) {
  AdapterInitializationStatus* status = future.result();
  // Check status for any mediation adapters you wish to use.
  // ..
} else {
  // Handle initialization error.
}

`AdView` 內對 `AdSize` 的變更

AdSize 現在包含常見橫幅廣告大小的靜態成員，並支援 AnchorAdaptive 和 InlineAdaptive 廣告大小，這些廣告大小會根據指定寬度和螢幕目前的螢幕方向，動態調整高度。

已將靜態 `AdSize` 常數新增至 `firebase::gma::AdSize`
`AdSize::kBanner`	行動行銷協會 (MMA) 橫幅廣告大小 (320x50 密度無關像素)
`AdSize::kFullBanner`	美國互動廣告協會 (IAB) 全尺寸橫幅廣告大小 (468x60 密度獨立像素)
`AdSize::kLargeBanner`	`kBanner` 的較高版本，通常為 320x100
`AdSize::kLeaderboard`	美國互動廣告協會 (IAB) 超級橫幅廣告大小 (728x90 密度獨立像素)
`AdSize::kMediumRectangle`	美國互動廣告協會 (IAB) 中矩形廣告大小 (300x250 密度獨立像素)

`firebase::gma::AdSize` 中的靜態方法，有助於建構 `AdSize` 執行個體
`GetLandscapeAnchoredAdaptiveBannerAdSize`	建立具有指定寬度和 Google 最佳化高度的 `AdSize`，以建立橫向模式的橫幅廣告
`GetPortraitAnchoredAdaptiveBannerAdSize`	Creates an `AdSize` with the given width and a Google-optimized height to create a banner ad in portrait mode
`GetCurrentOrientationAnchoredAdaptiveBannerAdSize`	Creates an `AdSize` with the given width and a Google-optimized height to create a banner ad given the current orientation
`GetInlineAdaptiveBannerAdSize`	根據橫幅廣告的最高高度，建立最合適的 `AdSize`。這項 `AdSize` 可讓 Google 伺服器選擇高度小於或等於指定高度上限的最佳廣告尺寸。
`GetLandscapeInlineAdaptiveBannerAdSize`	使用指定寬度和裝置的橫向高度建立 `InlineAdaptive` `AdSize`
`GetPortraitInlineAdaptiveBannerAdSize`	建立 `InlineAdaptive` `AdSize`，並指定寬度和裝置的直向高度。
`GetCurrentOrientationInlineAdaptiveBannerAdSize`	這個簡易方法會根據特定寬度，傳回目前介面方向的 `InlineAdaptive` `AdSize`。

之前

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

firebase::admob::AdSize ad_size;
ad_size.ad_size_type = firebase::admob::kAdSizeStandard;
ad_size.width = 320;
ad_size.height = 50;

// ad_parent is a reference to an iOS UIView or an Android Activity.
// banner_ad_unit is your ad unit id for banner ads.
banner_view->Initialize(ad_parent, banner_ad_unit, ad_size);

晚於

firebase::gma::AdView* ad_view = new firebase::gma::AdView();

// ad_parent is a reference to an iOS UIView or an Android Activity.
// banner_ad_unit is your ad unit id for banner ads.
banner_view->Initialize(ad_parent, banner_ad_unit, firebase::gma::AdSize.kBanner);

`AdRequest` 和全域設定

測試裝置 ID (TagForChildDirectedTreatment 和 TagForUnderAgeOfConsent) (先前由生日處理) 已從 AdRequest 移除，現在是全域 RequestConfiguration 的一部分。應用程式可能會在應用程式生命週期的早期階段，叫用 firebase::gma::SetRequestConfiguration() 來設定這些值。設定完成後，後續所有廣告載入作業都會採用這些設定。

firebase::gma::AdRequest 仍存在，因為它會提供載入廣告的情境資訊，包括關鍵字和選填的內容網址。

AdMob 的 AdRequest C 樣式結構已替換為具有方法的類別，可讓使用者在定義及附加至各種資訊清單時，獲得更優質的體驗。

重要AdRequest異動如下：

現在，額外資訊會與中介服務介面卡類別名稱建立關聯。傳送至 AdMob 服務的 Extras 應使用預設類別名稱，如下所示。
應用程式請求廣告時，可能會傳遞放送內容的網址。這樣一來，關鍵字指定目標就能讓廣告與顯示的其他內容相符。

之前

firebase::admob::AdRequest request;

// Keywords to be used in targeting.
const char* keywords[] = {"GMA", "C++", "Fun"};
request.keyword_count = sizeof(keywords) / sizeof(keywords[0]);
request.keywords = keywords;

// "Extra" key value pairs.
static const firebase::admob::KeyValuePair extras[] = {
      {"extra_name", "extra_value"}};
request.extras_count = sizeof(extras) / sizeof(extras[0]);
request.extras = kRequestExtras;

// Devices that should be served test ads.
const char* test_device_ids[] ={ "123", "4567", "890" };
request.test_device_id_count =
      sizeof(test_device_ids) / sizeof(test_device_ids[0]);
request.test_device_ids = test_device_ids;

// Sample birthday to help determine the age of the user.
request.birthday_day = 10;
request.birthday_month = 11;
request.birthday_year = 1975;

// Load Ad with the AdRequest.

晚於

// Do once after Google Mobile Ads C++ SDK initialization.
// These settings will affect all Ad Load operations.
firebase::gma::RequestConfiguration configuration;
configuration.max_ad_content_rating =
      firebase::gma::RequestConfiguration::kMaxAdContentRatingPG;
configuration.tag_for_child_directed_treatment =
      firebase::gma::RequestConfiguration::kChildDirectedTreatmentTrue;
configuration.tag_for_under_age_of_consent =
      firebase::gma::RequestConfiguration::kUnderAgeOfConsentFalse;
configuration.test_device_ids.push_back("1234");
configuration.test_device_ids.push_back("4567");
configuration.test_device_ids.push_back("890");
firebase::gma::SetRequestConfiguration(configuration);

// Then, more information must be provided via an AdRequest when
// loading individual ads.
firebase::gma::AdRequest ad_request;

// "Extra" key value pairs.
ad_request.add_keyword("GMA");
ad_request.add_keyword("C++");
ad_request.add_keyword("Fun");

// Content URL.
ad_request.set_content_url("www.example.com");

// Mediation Adapter Extras.
#if defined(Android)
const char* ad_network_extras_class_name =
    "com/google/ads/mediation/admob/AdMobAdapter";
#else  // iOS
const char* ad_network_extras_class_name = "GADExtras";
#endif

ad_request.add_extra(ad_network_extras_class_name, "extra_name", "extra_value");

// Load Ad with the AdRequest. See next section.

`AdResults`

LoadAd 現在會傳回 Future，其中包含所有 AdView、InterstitialAd 和 RewardedAd 廣告類型的 AdResult 物件。如果廣告請求成功放送，AdResult::is_successful 方法會傳回 true，否則會傳回 false。

如果失敗，AdResult 會包含 AdError 物件，其中含有問題的服務層級資訊，包括錯誤代碼、錯誤訊息和網域字串。

之前

firebase::Future<AdResult> future;

void load_ad() {
  // Assume an already created AdRequest object.
  future = ad_view->LoadAd(ad_request);
}

void your_game_loop() {
  if (future.status() == firebase::kFutureStatusComplete) {
    if(future.error() != firebase::admob::kAdMobErrorNone) {
      // There was either an internal SDK issue that caused the Future to
      // fail its completion, or AdMob failed to fulfill the ad request.
      // Details are unknown other than the Future’s error code returned
      // from future.error().
    } else {
      // The ad loaded successfully.
    }
  }
}

晚於

firebase::Future<AdResult> future;

void load_ad() {
  // Assumes a previously created AdRequest object.
  // See "AdRequest and Global Configuration" above.
  future = ad_view->LoadAd(ad_request);
}

void your_game_loop() {
  // Check the future status in your game loop:
  if (future.status() == firebase::kFutureStatusComplete) {
    if(future.error() != firebase::admob::kAdErrorCodeNone) {
      // There was an internal SDK issue that caused the Future to fail.
    } else {
      // Future completed successfully.  Check the GMA result.
      const AdResult* ad_result = future.result();
      if ( ad_result->is_successful() != true ) {
        // GMA failed to serve an ad. Gather information about the error.
        const AdError& ad_error = ad_result->ad_error();
        AdErrorCode error_code = ad_error.code();
        const std::string error_domain = ad_error.domain();
        const std::string error_message = ad_error.message();
      } else {
        // The ad loaded successfully.
      }
    }
  }
}

`AdListener` 個事件 (共 `AdView` 個)

AdMob 的 BannerView::Listener 類別已由 Google Mobile Ads C++ SDK 中的兩個不同監聽器類別取代：

AdListener 會追蹤廣告生命週期和使用者互動事件。
AdView 大小變更或移動時，系統會叫用 AdViewBoundingBoxListener。

AdMob `OnPresentationStateChanged` 回呼 Google Mobile Ads對應

新的 Google Mobile Ads C++ SDK 不包含 firebase::admob::BannerView::PresentationState 列舉型別和OnPresentationStateChanged接聽程式方法。

以下是在 AdView 的生命週期中偵測簡報狀態變更的替代方法：

`firebase::admob::BannerView::Listener OnPresentationStateChanged` 個事件	`firebase::gma::AdListener`對手
`kPresentationStateHidden`	叫用 `AdListener::OnAdClosed` 時，或 `AdView::Hide()` 成功完成非同步作業時
`kPresentationStateVisibleWithoutAd`	無，如果嘗試叫用未載入的 `AdView::Show()AdView`，就會發生錯誤。
`kPresentationStateVisibleWithAd`	呼叫 `AdListener::OnAdOpened` 時，或 `AdView::Show()` 成功完成非同步作業並傳回廣告時
`kPresentationStateOpenedPartialOverlay`	在叫用 `AdListener::OnAdOpened()` 後查詢周框，判斷顯示廣告的大小和位置。或者，您也可以查詢 `AdView` 的位置和 `AdSize`，並/或透過 `AdViewBoundingBoxListener` 監控周框。
`kPresentationStateCoveringUI`	請參閱上方的「`kPresentationStateOpenedPartialOverlay`」

「`RewardedAd`」現已成為課程

已淘汰的 Firebase AdMob C++ SDK 可透過 firebase::admob::rewarded_ad 命名空間中的一系列函式，放送獎勵廣告。這些函式已合併為新的 RewardedAd 類別，可透過與 InterstitialAd 類似的 API 介面放送廣告 (請參閱下一節)。

`InterstitialAd` 和 `RewardedAd` 監聽器

插頁式廣告和獎勵廣告都屬於全螢幕廣告。您可以安裝新的 FullScreenContentListener，監聽這些廣告類型的廣告生命週期事件，並安裝另一個 PaidEventListener，追蹤 AdMob 服務何時判定已發生付費事件。

RewardedAd 還有額外的監聽器，可監控使用者獲得的獎勵事件。

新的全螢幕廣告回呼方法

`FullScreenContentListener` 方法	`PaidEventListener` 方法	`UserEarnedRewardListener` 方法
`OnAdClicked`	`OnPaidEvent`	`OnUserEarnedReward`
`OnAdDismissedFullScreenContent`
`OnAdFailedToShowFullScreenContent`
`OnAdImpression`
`OnAdShowedFullScreenContent`

變更/移除/取代方法

下表列出新版 Google Mobile Ads C++ SDK 中變更的特定方法。有參數的方法仍會列出，但簽章已變更。

類別	Firebase AdMob C++ SDK API	Google Mobile Ads C++ SDK API	附註
`BannerView`	`MoveTo`	`AdView::SetPosition`
	`presentation_state`	已移除	由 `AdViewListener` 事件和 `AdView::Show` 與 `AdView::Hide` 未來結果處理。
	`SetListener`	`AdView::SetAdListener` `AdView::SetBoundingBoxListener` `AdView::SetPaidEventListener`	新的監聽器設計可提高偵測 `AdView` 生命週期事件的準確度。
	`Listener::OnPresentationStateChanged`	已移除	詳情請參閱上方的 `BannerView::SetListener`。
	`Listener::OnBoundingBoxChanged`	`AdViewBoundingBoxListener::OnBoundingBoxChanged`
InterstitialAd	`Initialize(AdParent parent, const char* ad_unit_id)`	`Initialize(AdParent parent)`	`ad_unit_id` 參數現在是 `LoadAd` 作業的一部分。
	`LoadAd(const AdRequest& request)`	`LoadAd(const char* ad_unit_id, const AdRequest& request)`
	`presentation_state`	已移除	已移除 `presentation_state` 列舉。使用 `FullScreenContentListener`。
	`SetListener`	`SetFullScreenContentListener` `SetPaidEventListener`
	`Destroy`	已移除	清除資源現在是 `RewardedAd` 解構函式的一部分。
`RewardedAd` (正式 `RewardedVideoAd`)	`Initialize`	`Initialize(AdParent parent)`	先前會將 `AdParent` 傳遞至 `Show`，但現在已成為初始化的一部分。
	`presentation_state`	已移除	已移除 `presentation_state` 列舉。使用 `FullScreenContentListener`。
	`SetListener`	`SetFullScreenContentListener` `SetPaidEventListener` `Show`	顯示 `RewardedAd` 時，也會定義 `UserEarnedReward` 監聽器。詳情請參閱下文。
	`Show(AdParent parent)`	`Show(UserEarnedRewardListener* listener)`

改用新版 Google Mobile Ads C++ SDK 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

移除舊版 API

RewardedVideoAd

NativeExpressAds

SDK 命名空間變更

命名空間 firebase::gma