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


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

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

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

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

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

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

RewardedVideoAd

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

NativeExpressAds

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

تغيير مساحة اسم حزمة SDK

تم نقل حزمة SDK إلى مساحة أسماء جديدة، ولها بنية دليل جديدة:

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

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

بنية الدليل

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

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

المكتبة

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

iOS

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

Android

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

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

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

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

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

حجم إعلان البانر الكامل (468×60 بكسل مستقل الكثافة) وفقًا لمعايير Interactive Advertising Bureau (IAB)
AdSize::kLargeBanner نسخة أطول من kBanner، عادةً ما تكون بحجم ‎320x100

AdSize::kLeaderboard

حجم إعلان ليدربورد وفقًا لمعايير Interactive Advertising Bureau (IAB) (728×90 بكسل مستقل الكثافة)
AdSize::kMediumRectangle حجم إعلان المستطيل المتوسط (300×250 بكسل مستقل الكثافة) وفقًا لمكتب Interactive Advertising Bureau (IAB)
الإجراءات الثابتة في 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 أو نقله.

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

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