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

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

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

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

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

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

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

RewardedVideoAd

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

NativeExpressAds

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

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

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

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

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

بنية الدليل

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

المكتبة

سيتم توفير حزمة تطوير البرامج (SDK) بلغة C++ لمنصة AdMob على Firebase كمكتبة ثابتة ضمن أرشيف إصدار حزمة تطوير البرامج (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) المتوقّفة نهائيًا للغة C++ في Firebase AdMob تسهّل عرض الإعلانات مقابل مكافأة من خلال مجموعة من الدوال في مساحة الاسم firebase::admob::rewarded_ad. تم دمج هذه الدوال في فئة RewardedAd جديدة تعرض الإعلانات باستخدام مساحة واجهة برمجة تطبيقات مشابهة لمساحة InterstitialAd (راجِع القسم التالي).

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

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

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

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

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

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