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


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

  • פרמטר פלט אופציונלי מציין אם אירעה שגיאת תלות לפני שתהליך האתחול התחיל.

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

המאפיין 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 אופציונלית של תוכן.

המבנה של 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::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
(לשעבר
RewardedVideoAd)
Initialize Initialize(AdParent parent) ‫AdParent הועבר בעבר אל Show, אבל עכשיו הוא חלק מההפעלה.
presentation_state הוסר הערך presentation_state הוסר. משתמשים ב-FullScreenContentListener.
SetListener SetFullScreenContentListener
SetPaidEventListener Show
מאזין UserEarnedReward מוגדר גם כשמוצג RewardedAd. מידע על סימון אירועים כהמרות מפורט בהמשך.
Show(AdParent parent) Show(UserEarnedRewardListener* listener)