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

הוצאה משימוש: Google Mobile Ads C++ SDK הווצא משימוש החל מ-17 ביוני 2024, ועליך להפסיק להשתמש בו בפרויקטים שבהם הוא עדיין לא נמצא בשימוש. הוא ייכנס לשלב הפסקת התחזוקה (EoM) ב-17 ביוני 2025. חשוב לשים לב שגרסאות של SDK שהושקו לפני תאריך EoM ימשיכו לפעול, אבל לא יפורסמו עוד תיקוני באגים או שינויים אחרי תאריך EoM.

במקום Google Mobile Ads C++ SDK, כדאי להשתמש ב-SDK ל-iOS ול-Android מ-AdMob. לקבלת תמיכה, אפשר לפנות אל פורום הטכני של Google Mobile Ads SDK.

הגרסה של Firebase C++ SDK v9.1.0 כוללת ערכת SDK חדשה של Google Mobile Ads C++.

Google Mobile Ads C++ SDK הוא ממשק API חדש שמשתלב עם השינויים המשמעותיים שבוצעו ב-2021 וב-2022 ב-Firebase AdMob C++ SDK ל-iOS ול-Android, כולל הסרת ממשקי API שהוצאו משימוש ותהליך חדש לעבודה עם סוגי מודעות במסך מלא.

הגרסה הישנה של SDK/ C++ SDK של Firebase (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 SDK החדש נמצאים במרחב השמות firebase::gma. מרחב השמות הישן firebase::admob הוצא משימוש יחד עם Firebase AdMob C++ SDK.

מבנה הספרייה

קובצי הכותרות הועברו לספרייה חדשה בתוך ארכיון ה-build:

Firebase AdMob C++ SDK שהוצא משימוש	ערכת ה-SDK החדשה של Google Mobile Ads ל-C++
include/firebase/admob	include/firebase/gma

ספרייה

ערכת ה-SDK של AdMob C++ ב-Firebase תסופק כספרייה סטטית בתוך ארכיון ה-build של ה-SDK של Firebase C++:

iOS

Firebase AdMob C++ SDK שהוצא משימוש	ערכת ה-SDK החדשה של Google Mobile Ads ל-C++
firebase_admob.xcframework	firebase_gma.xcframework

Android

Firebase AdMob C++ SDK שהוצא משימוש	SDK חדש של מודעות Google לנייד מסוג C++
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

כל פונקציית אתחול C++ SDK של Google Mobile Ads מחזירה מיד שני מדדי סטטוס:

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

• פרמטר ההחזרה הוא הפניה ל-firebase::Future. השדה Future מכיל את התוצאות של האיניציאליזציה האסינכרונית של מתאמי התיווך במכשיר.

אפשר להפעיל את C++ SDK של מודעות Google לנייד כדי לטעון מודעות שמוצגות על ידי 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 אופציונלית של תוכן.

המבנה AdRequest בסגנון C של AdMob הוחלף במחלקה בשיטות שמשפרות את חוויית המשתמש כשמגדירים רשימות מידע שונות ומוסיפים אותן.

אלה השינויים הבולטים ב-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. ה-method 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 של 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	ממשק API של C++ SDK למודעות Google לנייד	הערות
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	הוסרה	ניקוי המשאבים הוא עכשיו חלק מה-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)