الانتقال إلى حزمة C++ SDK الجديدة لإعلانات Google على الأجهزة الجوّالة


يتضمّن إصدار حزمة تطوير البرامج (SDK) ‏Firebase C++‏ 9.1.0 حزمة تطوير برامج (SDK) جديدة بلغة C++ من "إعلانات Google على الأجهزة الجوّالة".

إنّ حزمة تطوير البرامج (SDK) للغة C++ من "إعلانات Google على الأجهزة الجوّالة" هي واجهة برمجة تطبيقات جديدة تتضمّن التغييرات الرئيسية غير المتوافقة التي تم إجراؤها على حِزم تطوير البرامج (SDK) للغة C++ من Firebase AdMob لنظامَي التشغيل iOS وAndroid في عامَي 2021 و2022، بما في ذلك إزالة واجهات برمجة التطبيقات المتوقّفة نهائيًا، ومسار جديد عند استخدام أنواع الإعلانات بملء الشاشة.

تم وضع علامة الإيقاف النهائي على حزمة تطوير البرامج (SDK) القديمة بلغة C++ لمنصة Firebase AdMob (firebase::admob)، ولن تتلقّى أي تحديثات أو إصلاحات للأخطاء من الآن فصاعدًا.

ستبقى كلّ من حزمة تطوير البرامج (SDK) الجديدة بلغة C++ من "إعلانات Google على الأجهزة الجوّالة" (firebase::gma) وحزمة تطوير البرامج (SDK) القديمة بلغة C++ من Firebase AdMob (firebase::admob) جزءًا من أرشيفات الإصدار لحزمة تطوير البرامج (SDK) Firebase C++ خلال فترة إيقاف حزمة تطوير البرامج (SDK) بلغة C++ من Firebase AdMob نهائيًا.

إزالة واجهة برمجة التطبيقات القديمة

تمت إزالة واجهات برمجة التطبيقات التالية بالكامل من حزمة تطوير البرامج (SDK) للغة C++ من "إعلانات Google على الأجهزة الجوّالة".

RewardedVideoAd

تم استبدال مساحة الاسم RewardedVideoAd في AdMob بالفئة RewardedAd. يتشابه سلوك RewardedAd مع سلوك InterstitialAd، ولكنّه يتضمّن RewardedAdListener إضافيًا لتلقّي إشعار بمكافآت العناصر.

NativeExpressAds

تمّت الإشارة إلى NativeExpressAd في AdMob على أنّه متوقّف نهائيًا في كل حزمة Firebase AdMob C++ SDK. لذلك، لا يتم تضمين NativeExpressAd في حزمة SDK الجديدة لإعلانات Google على الأجهزة الجوّالة الخاصة بتطبيقات C++.

تغيير مساحة اسم حزمة تطوير البرامج (SDK)

تم نقل حزمة تطوير البرامج (SDK) إلى مساحة اسم جديدة، وأصبح لها بنية دليل جديدة:

مساحة الاسم firebase::gma

تتوفّر مصادر حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" الجديدة بلغة C++ في مساحة الاسم firebase::gma. تم إيقاف مساحة الاسم القديمة firebase::admob نهائيًا، بالإضافة إلى حزمة تطوير البرامج (SDK) لمنصة Firebase AdMob C++.

بنية الدليل

تم نقل ملفات العناوين إلى دليل جديد داخل أرشيف الإصدار:

حزمة C++ SDK المتوقّفة نهائيًا من Firebase AdMob حزمة تطوير البرامج الجديدة الخاصة بلغة C++‎ في "إعلانات Google على الأجهزة الجوّالة"
include/firebase/admob include/firebase/gma

المكتبة

سيتم توفير حزمة تطوير البرامج (SDK) بلغة C++ من Firebase AdMob كمكتبة ثابتة ضمن أرشيف إنشاء حزمة تطوير البرامج (SDK) Firebase C++:

iOS

حزمة C++ SDK المتوقّفة نهائيًا من Firebase AdMob حزمة تطوير البرامج الجديدة الخاصة بلغة C++‎ في "إعلانات Google على الأجهزة الجوّالة"
firebase_admob.xcframework firebase_gma.xcframework

Android

حزمة C++ SDK المتوقّفة نهائيًا من Firebase AdMob حزمة تطوير البرامج الجديدة الخاصة بلغة C++‎ في "إعلانات Google على الأجهزة الجوّالة"
libfirebase_admob.a libfirebase_gma.a

عمليات نقل البيانات الخاصة بالفئات والتعدادات والبُنى

يسرد الجدول أدناه فئات وتعدادات وبنيات محددة تم تغييرها أو إزالتها. في ما يلي ملخّص:

  • تمت إعادة تسمية BannerView إلى AdView.
  • تمت إزالة NativeAdExpressView.
  • يتم استبدال مساحة الاسم RewardedVideo بالفئة RewardedAd.
  • تمت إزالة التعداد PresentationState وأدوات المعالجة واستبدالها بالتعداد AdListener وأدوات المعالجة FullScreenContent.

  • تتم إزالة المَعلمات التالية كمَعلمات إعداد لكل إعلان في AdRequests:

    • إعداد أرقام تعريف الأجهزة الاختبارية
    • استهداف الإعلانات حسب العمر

    بدلاً من ذلك، يمكن الآن ضبط هذه المَعلمات في RequestConfiguration، وهو إعداد عام سيؤثر في جميع عمليات تحميل الإعلانات اللاحقة.

تم إيقافها نهائيًا firebase::admob namespace firebase::gma namespace جديدة
AdSizeType (تعداد) AdSize::Type (تعداد)
BannerView AdView
BannerView::Listener AdListener
AdViewBoundingBoxListener
PaidEventListener
BannerView::Position AdView::Position
BannerView::PresentationState تمت الإزالة
ChildDirectedTreatmentState RequestConfiguration::TagForChildDirectedTreatment
Gender (تعداد) تمت الإزالة
InterstitialAd::Listener FullScreenContentListener
PaidEventListener
KeyValuePair تمت الإزالة
NativeExpressAdView تمت الإزالة
PollableRewardListener تمت الإزالة
RewardItem AdReward
RewardedVideoAd (مساحة الاسم) RewardedAd (الصف)
RewardedVideoAd::Listener FullScreenContentListener
PaidEventListener
UserEarnedRewardListener
AdMobError (تعداد) AdErrorCode (تعداد)
RewardItem AdReward

إعداد حزمة تطوير البرامج (SDK)

تعرض كل دالة تهيئة لحزمة تطوير البرامج C++ لإعلانات Google على الأجهزة الجوّالة مؤشّرَي حالة على الفور، وهما:

  • تعرض مَعلمة اختيارية ما إذا حدث خطأ في التبعية قبل بدء عملية الإعداد.

  • مَعلمة الإرجاع هي مرجع إلى firebase::Future. يحتوي Future على نتائج الإعداد غير المتزامن لبرامج التكيّف الخاصة بالتوسّط على الجهاز.

مع أنّه يمكن استدعاء حزمة تطوير البرامج (SDK) الخاصة بتطبيقات C++‎ من "إعلانات Google على الأجهزة الجوّالة" لتحميل الإعلانات التي تعرضها 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
حجم إعلان البانر الخاص بـ "رابطة التسويق عبر الأجهزة الجوّالة" (MMA) (320×50 بكسل مستقل الكثافة)

AdSize::kFullBanner
حجم إعلان البانر الكامل الصادر عن مكتب الإعلانات التفاعلية (IAB) (468x60 بكسل مستقل الكثافة)
AdSize::kLargeBanner نسخة أطول من kBanner، وعادةً ما تكون 320x100

AdSize::kLeaderboard
حجم إعلان الليدربورد الذي يحدّده مكتب الإعلانات التفاعلية (IAB) (‏728×90 وحدة بكسل مستقلة الكثافة)
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-style في 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 بفئتَي مستمعين مختلفتَين في حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" بلغة C++:

  • يتتبّع AdListener أحداث دورة حياة الإعلان وتفاعُل المستخدم.
  • يتم استدعاء AdViewBoundingBoxListener عند تغيير حجم AdView أو نقله.

عمليات ربط OnPresentationStateChanged دالة ردّ الاتصال Google Mobile Ads في AdMob

لا يتضمّن الإصدار الجديد من حزمة تطوير البرامج (SDK) للغة C++ من "إعلانات Google على الأجهزة الجوّالة" firebase::admob::BannerView::PresentationState النوع المُعدَّد وطريقة 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 هو الآن صف

كانت حزمة تطوير البرامج (SDK) المتوقّفة نهائيًا لمنصة Firebase AdMob C++‎ تسهّل عرض الإعلانات مقابل مكافأة من خلال مجموعة من الدوال في مساحة الاسم firebase::admob::rewarded_ad. تم دمج هذه الدوال في فئة RewardedAd جديدة تعرض الإعلانات باستخدام مساحة واجهة برمجة تطبيقات مشابهة لمساحة InterstitialAd (راجِع القسم التالي).

المستمعون إلى InterstitialAd وRewardedAd

يتم تصنيف كلّ من الإعلانات البينية والإعلانات مقابل مكافأة كإعلانات بملء الشاشة. يمكن تثبيت FullScreenContentListener جديد للاستماع إلى أحداث دورة حياة الإعلان لهذه الأنواع من الإعلانات، ويمكن تثبيت PaidEventListener منفصل لتتبُّع الوقت الذي اعتبرت فيه خدمة AdMob أنّه قد وقع حدث مدفوع.

تحتوي RewardedAd على أداة معالجة إضافية لتتبُّع أحداث المكافآت التي يحصل عليها المستخدم.

طُرق جديدة لردّ الاتصال في الإعلانات بملء الشاشة

FullScreenContentListener طرق PaidEventListener طرق UserEarnedRewardListener طرق
OnAdClicked OnPaidEvent OnUserEarnedReward
OnAdDismissedFullScreenContent
OnAdFailedToShowFullScreenContent
OnAdImpression
OnAdShowedFullScreenContent

تم تغيير الطرق أو إزالتها أو استبدالها

يسرد الجدول أدناه الطرق المحدّدة التي تم تغييرها في حزمة تطوير البرامج (SDK) الجديدة لإعلانات Google على الأجهزة الجوّالة بلغة C++. ستبقى الطرق التي تتضمّن المَعلمات المُدرَجة، ولكن تم تغيير تواقيعها.

الفئة Firebase AdMob C++ SDK API واجهة برمجة التطبيقات لحزمة تطوير البرامج (SDK) الخاصة بـ "إعلانات Google على الأجهزة الجوّالة" بلغة C++ ملاحظات
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 تمت الإزالة أصبح تنظيف الموارد جزءًا من أداة التدمير 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)