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

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

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

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

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

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

تمت إزالة واجهات برمجة التطبيقات التالية بالكامل من حزمة تطوير البرامج (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 لمحاولة الربط Firebase C++:

عمليات نقل البيانات في الفئات والعناصر والبنى

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

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

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

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

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

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

قبل

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 بنية AdMob على غرار C بصفّة تتضمّن طُرقًا توفّر تجربة أفضل للمستخدم عند تحديد قوائم المعلومات المختلفة وإضافتها إليها.

في ما يلي التغييرات البارزة في 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++. تظل الطرق التي تتضمّن مَعلمات مُدرَجة، ولكن تغيّر توقيعاتها.