انتقل إلى Google Mobile Ads C++ SDK الجديد

يقدم إصدار Firebase C++ SDK v9.1.0 حزمة جديدة من Google Mobile Ads C++ SDK.

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

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

سيظل كل من Google Mobile Ads C++ SDK الجديد ( firebase::gma ) وFirebase AdMob C++ SDK القديم ( firebase::admob ) جزءًا من أرشيفات الإصدار لـ Firebase C++ SDK أثناء نافذة إهمال Firebase AdMob C++ SDK.

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

تمت إزالة واجهات برمجة التطبيقات التالية من Google Mobile Ads C++ SDK بالكامل.

RewardedVideoAd

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

NativeExpressAds

تم بالفعل وضع علامة على NativeExpressAd الخاص بـ AdMob على أنه مهمل في كل حزمة SDK من Firebase AdMob C++. ولذلك، لم يتم تضمين NativeExpressAd في Google Mobile Ads C++ SDK الجديد.

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

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

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

توجد مصادر Google Mobile Ads C++ SDK الجديدة في مساحة الاسم firebase::gma . تم إهمال مساحة الاسم القديمة firebase::admob بالإضافة إلى Firebase AdMob C++ SDK.

بنية الدليل

تم نقل ملفات الرأس إلى دليل جديد داخل أرشيف البناء:

مكتبة

سيتم توفير Firebase AdMob C++ SDK كمكتبة ثابتة داخل أرشيف إنشاء Firebase C++ SDK:

ترحيلات الفئة والتعداد والبنية

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

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

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

  • تكوين معرفات جهاز الاختبار
  • استهداف الإعلانات على أساس العمر

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

تهيئة SDK

تقوم كل وظيفة تهيئة C++ SDK لإعلانات Google على الجوال بإرجاع مؤشرين للحالة على الفور:

• تنقل معلمة الخروج الاختيارية ما إذا كان قد حدث خطأ في التبعية قبل بدء عملية التهيئة.

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

في حين أنه قد يتم استدعاء Google Mobile Ads C++ SDK لتحميل الإعلانات التي يعرضها 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 بفئتين مستمعتين متميزتين في Google Mobile Ads C++ SDK:

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

AdMob OnPresentationStateChanged رد الاتصال تعيينات إعلانات Google للجوال

لم يتم تضمين النوع المُعدَّد firebase::admob::BannerView::PresentationState وأسلوب المستمع OnPresentationStateChanged في حزمة SDK C++ لإعلانات Google على الأجهزة المحمولة الجديدة.

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

RewardedAd أصبح الآن فئة

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

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

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

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

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

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

يسرد الجدول أدناه الطرق المحددة التي تم تغييرها في Google Mobile Ads C++ SDK الجديدة. تظل الطرق ذات المعلمات المدرجة ولكن تم تغيير توقيعاتها.