מעבר לגרסה החדשה של Google Mobile Ads C++ SDK


במסגרת השקת 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 שמתאים במיוחד למודעות באנר, בהתאם לגובה המקסימלי

השדה 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 והגדרה גלובלית

מזהי המכשירים לבדיקה, 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)