במסגרת השקת Firebase C++ SDK v9.1.0, אנחנו משיקים ערכת Google Mobile Ads SDK חדשה ל-C++.
Google Mobile Ads C++ SDK הוא ממשק API חדש שמשתלב עם השינויים המשמעותיים שבוצעו ב-2021 וב-2022 ב-Firebase AdMob C++ SDK ל-iOS ול-Android, כולל הסרת ממשקי API שהוצאו משימוש ותהליך חדש לעבודה עם סוגי מודעות במסך מלא.
ערכת ה-SDK הישנה של Firebase AdMob ל-C++ (firebase::admob
) סומנה כמיושנת, ולא יקבלו לה עדכונים או תיקוני באגים מעכשיו והלאה.
גם ה-SDK החדש של Google Mobile Ads ל-C++ (firebase::gma
) וגם ה-SDK הישן של Firebase AdMob ל-C++ (firebase::admob
) יישארו חלק מארכיוני ה-build של ה-SDK של Firebase C++ במהלך חלון ההוצאה משימוש של ה-SDK של Firebase AdMob ל-C++.
הסרה של ממשקי 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 שהוצא משימוש | גרסת C++ SDK חדשה של Google Mobile Ads |
---|---|
include/firebase/admob |
include/firebase/gma |
ספרייה
Firebase AdMob C++ SDK יסופק כספרייה סטטית בארכיון ה-build של Firebase C++ SDK:
iOS
Firebase AdMob C++ SDK שהוצא משימוש | גרסת C++ SDK חדשה של Google Mobile Ads |
---|---|
firebase_admob.xcframework |
firebase_gma.xcframework |
Android
Firebase AdMob C++ SDK שהוצא משימוש | גרסת C++ SDK חדשה של Google Mobile Ads |
---|---|
libfirebase_admob.a |
libfirebase_gma.a |
העברות של סוגים של מחלקות, ערכים מוגדרים מראש ומבנים
בטבלה הבאה מפורטות כיתות, ערכים מוגדרים מראש ומבנים ספציפיים ששונו או הוסרו. זהו סיכום של השינויים:
- השם של
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 |
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 (class) |
RewardedVideoAd::Listener |
FullScreenContentListener PaidEventListener UserEarnedRewardListener |
AdMobError (enum) |
AdErrorCode (enum) |
RewardItem |
AdReward |
אתחול ה-SDK
כל פונקציית אתחול של Google Mobile Ads SDK ב-C++ מחזירה מיד שני אינדיקטורים של סטטוס:
פרמטר out אופציונלי מציין אם אירעה שגיאת תלות לפני תחילת תהליך האינטראקציה.
פרמטר ההחזרה הוא הפניה ל-
firebase::Future
. השדהFuture
מכיל את התוצאות של האיניציאליזציה האסינכרונית של מתאמי התיווך במכשיר.
אפשר להפעיל את Google Mobile Ads C++ SDK כדי לטעון מודעות שמוצגות על ידי AdMob ברגע שחוזרת פונקציית האיפוס, אבל רשתות אחרות של מודעות לא יציג ��ודעות עד שהמתאם המתאים של תהליך בחירת הרשת יופעל באופן מלא. התהליך הזה מתבצע באופן אסינכרוני. לכן, אם אתם משתמשים בתהליך בחירת הרשת (Mediation) להצגת מודעות באפליקציה, מומלץ להמתין עד שהבעיה ב-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 |
גודל מודעה בפורמט מלבן בינוני של הרשות לפרסום אינטראקטיבי (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 אופציונ��ית של תוכן.
המבנה מסוג struct בסגנון C של AdMob AdRequest
הוחלף בכיתה עם שיטות שמספקות חוויית משתמש טובה יותר כשמגדירים את רשימות המידע השונות ומצרפים אליהן פריטים.
אלה השינויים הבולטים ב-AdRequest
:
- התוספים משויכים עכשיו לשם של מחלקת מתאם בחירת הרשת. כששולחים פרטים נוספים לשירות 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 SDK ל-C++:
AdListener
עוקב אחרי אירועים במחזור החיים של מודעות ואירועי אינטראקציה של משתמשים.AdViewBoundingBoxListener
מופעל כשמשנים את הגודל או המיקום שלAdView
.
מיפויים של OnPresentationStateChanged
קריאה חוזרת (callback) Google Mobile Ads ב-AdMob
הסוג המנומר firebase::admob::BannerView::PresentationState
ו-method של המאזין 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
היא עכשיו כיתה
גרסת ה-SDK של Firebase AdMob ב-C++ שיצאה משימוש אפשרה להציג מודעות מתגמלות באמצעות אוסף פונקציות במרחב השמות firebase::admob::rewarded_ad
. הפונקציות האלה אוחדו לכיתה חדשה בשם RewardedAd
, שמציגה מודעות עם ממשק API דומה ל-InterstitialAd
(ראו הקטע הבא).
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 |
העיצוב החדש של ה-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
|
SetFullScreenContentListener SetPaidEventListener
|
||
Destroy
|
הוסרה | ניקוי המשאבים הוא עכשיו חלק מה-destructor של RewardedAd .
|
|
RewardedAd (formally RewardedVideoAd )
|
Initialize
|
Initialize(AdParent parent)
|
בעבר, הערך של AdParent הועבר אל Show , אבל עכשיו הוא חלק מההפעלה.
|
presentation_state
|
הוסרה | המניין presentation_state הוסר. משתמשים ב-FullScreenContentListener .
|
|
SetListener
|
SetFullScreenContentListener SetPaidEventListener
Show
|
מאזין UserEarnedReward מוגדר גם כשמציגים RewardedAd . מידע על סימון אירועים כהמרות מפורט בהמשך.
|
|
Show(AdParent parent)
|
Show(UserEarnedRewardListener* listener)
|