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

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

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

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

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

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

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

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) لخدمة AdMob من Firebase بلغة C++.

بنية الدليل

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

المكتبة

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

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

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

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

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

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

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

إعداد حزمة تطوير البرامج (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 التي لها ارتفاع ديناميكي استنادًا إلى العرض المحدّد واتجاه الشاشة الحالي.

قبل

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) لإعلانات Google على الأجهزة الجوّالة الخاصة بتطبيقات ++C النوع المُعدَّد firebase::admob::BannerView::PresentationState وطريقة معالجة الأحداث OnPresentationStateChanged.

في ما يلي طرق بديلة لرصد تغييرات حالة العرض في دورة حياة AdView:

RewardedAd هو الآن صف

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

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

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

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

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

تم تغيير/إزالة/استبدال الطرق

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