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
列舉和事件監聽器已移除,並替換為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 |
建立 AdSize ,其寬度為指定值,高度則由 Google 最佳化,以便在直向模式中建立橫幅廣告 |
GetCurrentOrientationAnchoredAdaptiveBannerAdSize |
建立具有指定寬度和 Google 最佳化高度的 AdSize ,以便根據目前的方向建立橫幅廣告 |
GetInlineAdaptiveBannerAdSize |
根據最大高度建立最適合橫幅廣告的 AdSize 這個 |
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 服務的額外項目應使用下方定義的預設類別名稱。
- 請求廣告時,應用程式可能會傳遞所放送內容的網址。這樣可讓指定關鍵字比對廣告和顯示的其他內容。
早於
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
事件
我們已在 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 介面廣告 (請參閱下一節)。
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)
|