改用新版 Google Mobile Ads C++ SDK


Firebase C++ SDK 9.1.0 版本推出了新的 Google Mobile Ads C++ SDK。

Google Mobile Ads C++ SDK 是新的 API 介面,整合了 2021 年和 2022 年對 Firebase AdMob C++ SDK for iOS 和 Android 所做的重大變更,包括移除已淘汰的 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

在每個 Firebase AdMob C++ SDK 中,AdMob 的 NativeExpressAd 已標示為已淘汰。因此,新版 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 列舉和事件監聽器已移除,並替換為 AdListenerFullScreenContent 事件監聽器。
  • 下列參數已從 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 現在包含常見橫幅廣告大小的靜態成員,並支援 AnchorAdaptiveInlineAdaptive 廣告大小,這些廣告大小的高度會根據指定的寬度和螢幕目前的方向而變動。

將靜態 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 建立 AdSize,其寬度為指定值,高度則由 Google 最佳化,以便在直向模式中建立橫幅廣告
GetCurrentOrientationAnchoredAdaptiveBannerAdSize 建立具有指定寬度和 Google 最佳化高度的 AdSize,以便根據目前的方向建立橫幅廣告
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 TagForChildDirectedTreatmentTagForUnderAgeOfConsent (先前由生日處理) 已從 AdRequest 中移除,現在是全域 RequestConfiguration 的一部分。應用程式可能會在應用程式生命週期初期叫用 firebase::gma::SetRequestConfiguration(),以便設定這些值。設定完成後,所有後續的廣告載入作業都會遵循這些設定。

firebase::gma::AdRequest 仍會存在,因為它可提供載入廣告的內容比對資訊,包括關鍵字和選用的內容網址。

AdMob 的 AdRequest C 樣式結構體已改為含有方法的類別,可在定義及附加各種資訊清單時,提供更優質的使用者體驗。

以下是重要的 AdRequest 變更:

  • 額外項目現在會與中介服務適配器類別名稱建立關聯。傳送至 AdMob 服務的額外項目應使用下方定義的預設類別名稱。
  • 請求廣告時,應用程式可能會傳遞所放送內容的網址。這樣可讓指定關鍵字比對廣告和顯示的其他內容。

早於

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,其中包含所有 AdViewInterstitialAdRewardedAd 廣告類型的 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.
      }
    }
  }
}

AdView 中的 AdListener 事件

我們已在 Google Mobile Ads C++ SDK 中,將 AdMob 的 BannerView::Listener 類別替換為兩個不同的事件監聽器類別:

  • 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 介面廣告 (請參閱下一節)。

InterstitialAdRewardedAd 事件監聽器

插頁式廣告和獎勵廣告都視為全螢幕廣告。您可以安裝新的 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::ShowAdView::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)