בגרסה 9.1.0 של Google Mobile Ads SDK ל-Firebase C++, הוספנו את Google Mobile Ads C++ SDK.
Google Mobile Ads C++ SDK הוא ממשק API חדש שמשלב את שינויי התוכנה שעלולים לגרום לכשל שבוצעו ב-Firebase AdMob C++ SDK ל-iOS ול-Android בשנים 2021 ו-2022, כולל הסרת ממשקי API שהוצאו משימוש ותהליך חדש לעבודה עם סוגי מודעות במסך מלא.
ה-SDK הישן של Firebase AdMob C++ (firebase::admob) הוצא משימוש, ולא יקבל יותר עדכונים או תיקוני באגים.
גם ה-Google Mobile Ads C++ SDK החדש (firebase::gma) וגם ה-Firebase AdMob C++ SDK הישן (firebase::admob) יישארו חלק מארכיוני ה-build של ה-SDK של Firebase C++ במהלך חלון ההוצאה משימוש של Firebase AdMob C++ SDK.
הסרת ה-API הקודם
ממשקי ה-API הבאים הוסרו לחלוטין מ-Google Mobile Ads C++ SDK.
RewardedVideoAd
מרחב השמות RewardedVideoAd של AdMob הוחלף במחלקה RewardedAd. RewardedAd פועל באופן דומה ל-InterstitialAd, אבל כולל RewardedAdListener נוסף כדי לקבל התראות על פרסים של פריטים.
NativeExpressAds
ה-NativeExpressAd של AdMob כבר סומן כהוצאה משימוש בכל Firebase AdMob C++ SDK. לכן, NativeExpressAd לא נכלל בגרסה החדשה של Google Mobile Ads C++ SDK.
שינוי מרחב השמות של ה-SDK
ה-SDK הועבר למרחב שמות חדש, ויש לו מבנה ספרייה חדש:
מרחב שמות firebase::gma
המקורות של Google Mobile Ads C++ SDK החדש נמצאים במרחב השמות firebase::gma. מרחב השמות הישן יותר firebase::admob הוצא משימוש יחד עם Firebase AdMob C++ SDK.
מבנה הספרייה
קובצי הכותרת הועברו לספרייה חדשה בתוך ארכיון ה-build:
| ערכת Firebase AdMob C++ SDK שהוצאה משימוש | Google Mobile Ads C++ SDK החדשה |
|---|---|
include/firebase/admob |
include/firebase/gma |
ספרייה
Firebase AdMob C++ SDK יסופק כספרייה סטטית בארכיון ה-build של 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 |
העברות של מחלקות, טיפוסי enum ומבנים
בטבלה הבאה מפורטים מחלקות, טיפוסי enum ומבנים ספציפיים שהשתנו או הוסרו. כך זה נראה:
- השם של
BannerViewהשתנה לשםAdView. - האפשרות
NativeAdExpressViewהוסרה. - מרחב השמות
RewardedVideoמוחלף בכיתהRewardedAd. - המאזינים והספירה של
PresentationStateהוסרו והוחלפו במאזינים שלAdListenerו-FullScreenContent. הפרמטרים הבאים הוסרו כפרמטרים של הגדרה לכל מודעה ב-
AdRequests:- הגדרת מזהים של מכשירי בדיקה
- טירגוט מודעות לפי גיל
במקום זאת, אפשר להגדיר את הפרמטרים האלה ב-
RequestConfiguration, שהיא הגדרה גלובלית שתשפיע על כל טעינות המודעות הבאות.
הוצא משימוש firebase::admob namespace |
firebase::gma namespace חדש |
|---|---|
AdSizeType (enum) |
AdSize::Type (enum) |
BannerView |
AdView |
BannerView::Listener |
AdListenerAdViewBoundingBoxListenerPaidEventListener |
BannerView::Position |
AdView::Position |
BannerView::PresentationState |
הוסר |
ChildDirectedTreatmentState |
RequestConfiguration::TagForChildDirectedTreatment |
Gender (enum) |
הוסר |
InterstitialAd::Listener |
FullScreenContentListenerPaidEventListener |
KeyValuePair |
הוסר |
NativeExpressAdView |
הוסר |
PollableRewardListener |
הוסר |
RewardItem |
AdReward |
RewardedVideoAd (מרחב שמות) |
RewardedAd (כיתה) |
RewardedVideoAd::Listener |
FullScreenContentListenerPaidEventListenerUserEarnedRewardListener |
AdMobError (enum) |
AdErrorCode (enum) |
RewardItem |
AdReward |
אתחול ה-SDK
כל פונקציית אתחול של Google Mobile Ads C++ SDK מחזירה מיד שני אינדיקטורים של סטטוס:
פרמטר פלט אופציונלי מציין אם אירעה שגיאת תלות לפני שתהליך האתחול התחיל.
הפרמטר שמוחזר הוא הפניה אל
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.
}
שינויים ב-AdSize בתוך AdView
AdSize מכיל עכשיו איברים סטטיים של גדלים נפוצים של מודעות באנר, ותומך בגדלים של מודעות AnchorAdaptive ו-InlineAdaptive שיש להם גובה דינמי על סמך הרוחב הנתון והכיוון הנוכחי של המסך.
נוספו AdSize קבועים סטטיים אל
firebase::gma::AdSize |
|
|---|---|
AdSize::kBanner |
גודל מודעת באנר של Mobile Marketing Association (MMA) (320x50 פיקסלים שלא תלויים בצפיפות) |
AdSize::kFullBanner |
גודל מודעת באנר מלאה של הרשות לפרסום אינטראקטיבי (IAB) (468x60 פיקסלים שלא תלויים בצפיפות) |
AdSize::kLargeBanner |
גרסה גבוהה יותר של kBanner, בדרך כלל בגודל 320x100 |
AdSize::kLeaderboard |
גודל מודעת Leaderboard של הרשות לפרסום אינטראקטיבי (IAB) (728x90 פיקסלים שלא תלויים בצפיפות) |
AdSize::kMediumRectangle |
גודל מודעה של מלבן בינוני של Interactive Advertising Bureau (IAB) (300x250 פיקסלים שלא תלויים בצפיפות) |
שיטות סטטיות ב-firebase::gma::AdSize שעוזרות ליצור מופעים של AdSize |
|
|---|---|
GetLandscapeAnchoredAdaptiveBannerAdSize |
יוצרת AdSize ברוחב הנתון ובגובה שעבר אופטימיזציה על ידי Google, כדי ליצור מודעת באנר בפריסה לרוחב |
GetPortraitAnchoredAdaptiveBannerAdSize |
יוצרת AdSize ברוחב שצוין ובגובה שמותאם על ידי Google, כדי ליצור מודעת באנר במצב לאורך |
GetCurrentOrientationAnchoredAdaptiveBannerAdSize |
יוצרת AdSize עם הרוחב שצוין וגובה שעבר אופטימיזציה על ידי Google, כדי ליצור מודעת באנר בהתאם לכיוון הנוכחי |
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 והגדרה גלובלית
מזהי מכשירי הבדיקה, TagForChildDirectedTreatment ו-TagForUnderAgeOfConsent (שבעבר טופלו על ידי יום ההולדת) הוסרו מ-AdRequest ועכשיו הם חלק מ-RequestConfiguration גלובלי. אפליקציות יכולות להפעיל את firebase::gma::SetRequestConfiguration() בשלב מוקדם במחזור החיים של האפליקציה כדי להגדיר את הערכים האלה. כל פעולות הטעינה של המודעות יתבצעו בהתאם להגדרות האלה אחרי שהן יוגדרו.
השדה firebase::gma::AdRequest עדיין קיים כי הוא מספק מידע על ההקשר לטעינת מודעות, כולל מילות מפתח וכתובת URL אופציונלית של תוכן.
המבנה של AdRequest בסגנון C ב-AdMob הוחלף במחלקה עם שיטות שמספקות חוויית משתמש טובה יותר כשמגדירים את רשימות המידע השונות ומוסיפים להן נתונים.
הנה השינויים הבולטים ב-AdRequest:
- התוספות משויכות עכשיו לשם מחלקה של מתאם לבחירת רשת (Mediation). בתוספות שנשלחות לשירות AdMob צריך להשתמש בשם ברירת המחדל של המחלקה, כמו שמוגדר בהמשך.
- כשאפליקציות שולחות בקשה להצגת מודעה, הן יכולות להעביר כתובת URL של התוכן שהן מציגות. כך אפשר להתאים את המודעה לתוכן אחר שמוצג באמצעות טירגוט לפי מילות מפתח.
לפני
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 שמכיל אובייקט AdResult לכל סוגי המודעות AdView, InterstitialAd ו-RewardedAd. השיטה 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
הכיתה BannerView::Listener של AdMob הוחלפה בשתי כיתות מאזינים נפרדות ב-Google Mobile Ads C++ SDK:
AdListenerעוקב אחרי אירועים במחזור החיים של המודעה ובאינטראקציה של המשתמשים.- הפונקציה
AdViewBoundingBoxListenerמופעלת כשמשנים את הגודל שלAdViewאו כשמזיזים אותו.
מיפויים של קריאות חוזרות (callback) ב-AdMob OnPresentationStateChanged Google Mobile Ads
הסוג הממוספר firebase::admob::BannerView::PresentationState ושיטת המאזין OnPresentationStateChanged לא כלולים ב-Google Mobile Ads C++ SDK החדש.
אלה דרכים חלופיות לזהות שינויים במצב המצגת במחזור החיים של 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 שמציגה מודעות עם ממשק API דומה ל-InterstitialAd (ראו את הקטע הבא).
מאזינים בInterstitialAd ובRewardedAd
גם מודעות מעברון וגם מודעות מתגמלות נחשבות למודעות במסך מלא. אפשר להתקין FullScreenContentListener חדש כדי להאזין לאירועים במחזור החיים של המודעה בסוגי המודעות האלה, ואפשר להתקין PaidEventListener נפרד כדי לעקוב אחרי המקרים שבהם שירות AdMob קבע שהתרחש אירוע בתשלום.
ל-RewardedAd יש listener נוסף למעקב אחרי אירועים מתגמלים שהמשתמשים הרוויחו.
שיטות חדשות של שיטת קריאה חוזרת (callback) למודעות במסך מלא
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::SetAdListenerAdView::SetBoundingBoxListenerAdView::SetPaidEventListener |
העיצוב החדש של ה-listener משפר את הדיוק בזיהוי אירועים במחזור החיים של 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
|
SetFullScreenContentListenerSetPaidEventListener
|
||
Destroy
|
הוסר | ניקוי המשאבים הוא עכשיו חלק מהמפרק (destructor) של RewardedAd.
|
|
RewardedAd(לשעבר RewardedVideoAd)
|
Initialize
|
Initialize(AdParent parent)
|
AdParent הועבר בעבר אל Show, אבל עכשיו הוא חלק מההפעלה.
|
presentation_state
|
הוסר | הערך presentation_state הוסר. משתמשים ב-FullScreenContentListener.
|
|
SetListener
|
SetFullScreenContentListenerSetPaidEventListener
Show
|
מאזין UserEarnedReward מוגדר גם כשמוצג RewardedAd. מידע על סימון אירועים כהמרות מפורט בהמשך.
|
|
Show(AdParent parent)
|
Show(UserEarnedRewardListener* listener)
|