改用新版 Google Mobile Ads C++ SDK


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

Google 行動廣告 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

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 建立 AdSize,並指定寬度和 Google 最佳化高度,以建立橫向模式的橫幅廣告
GetPortraitAnchoredAdaptiveBannerAdSize 建立 AdSize,並指定寬度,高度則由 Google 調整至最佳狀態,以直向模式建立橫幅廣告
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.
      }
    }
  }
}

AdView中的 AdListener 個事件

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)