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

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

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

בגרסה 9.1.0 של Firebase C++ SDK, הושק Google Mobile Ads C++ SDK חדש.

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

הגרסה הישנה של Firebase AdMob C++ SDK‏ (firebase::admob) סומנה כגרסה שיצאה משימוש, ולא יתבצעו בה עדכונים או תיקוני באגים בעתיד.

ה-SDK החדש של Google Mobile Ads C++‎‏ (firebase::gma) וה-SDK הישן של Firebase AdMob C++‎‏ (firebase::admob) יישארו חלק מארכיוני ה-build של Firebase C++ SDK במהלך תקופת ההוצאה משימוש של Firebase AdMob C++‎‏ SDK.

הסרה של API מדור קודם

ממשקי ה-API הבאים הוסרו לחלוטין מ-Google Mobile Ads C++ SDK.

RewardedVideoAd

מרחב השמות RewardedVideoAd של AdMob הוחלף במחלקה RewardedAd. הסמל RewardedAd דומה לסמל InterstitialAd אבל כולל RewardedAdListener נוסף לקבלת התראה על תגמולים על פריטים.

NativeExpressAds

‫AdMob SDK NativeExpressAd כבר סומן כהוצאה משימוש בכל אחד מהם Firebase AdMob C++ SDK. לכן, NativeExpressAd לא נכלל ב-Google Mobile Ads C++ SDK החדש.

שינוי של namespace ב-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 יסופק כספרייה סטטית בארכיון של גרסת ה-SDK:Firebase C++

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 ו-struct

בטבלה הבאה מפורטים מחלקות, סוגי enum ומבני struct ספציפיים ששונו או הוסרו. סיכום:

• השם של BannerView השתנה לAdView.
• האפשרות NativeAdExpressView מוסרת.
• מרחב השמות RewardedVideo מוחלף במחלקה RewardedAd.
• הספירה PresentationState והפונקציות event listener הוסרו והוחלפו בפונקציות AdListener ו-FullScreenContent event listener.

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

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

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

יכול להיות ש-Google Mobile Ads C++ SDK יופעל כדי לטעון מודעות שמוצגות דרך AdMob ברגע שפונקציית האתחול תחזיר ערך, אבל רשתות אחרות של מודעות לא יציגו מודעות עד שהמתאם המתאים שלהן לבחירת רשתות יושלם. התהליך הזה מתבצע באופן אסינכרוני. לכן, אם אתם משתמשים בתהליך בחירת הרשת (Ad 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. השיטה 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 או כשמעבירים אותו.

מיפויים של OnPresentationStateChanged קריאות חוזרות (callback) Google Mobile Ads ב-AdMob

הfirebase::admob::BannerView::PresentationState סוג המונה ושיטת ה-listener לא נכללים ב-Google Mobile Ads C++ SDK החדש.OnPresentationStateChanged

אלה דרכים חלופיות לזיהוי שינויים במצב המצגת במחזור החיים של 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 (ראו בקטע הבא).

פונקציות מסוג listener של InterstitialAd ושל RewardedAd

גם מודעות מעברון וגם מודעות מתגמלות נחשבות למודעות במסך מלא. אפשר להתקין FullScreenContentListener חדש כדי להאזין לאירועים במחזור החיים של מודעות מהסוגים האלה, ואפשר להתקין PaidEventListener נפרד כדי לעקוב אחרי המקרים שבהם שירות AdMob קבע שאירוע בתשלום התרחש.

‫RewardedAd יש listener נוסף למעקב אחרי אירועי תגמול שהמשתמשים הרוויחו.

שיטות חדשות לקריאה חוזרת של מודעות במסך מלא

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	העיצוב החדש של פונקציות event 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)