به Google Mobile Ads C++ SDK جدید مهاجرت کنید

انتشار نسخه ۹.۱.۰ کیت توسعه نرم‌افزار Firebase C++ یک کیت توسعه نرم‌افزار C++ جدید برای تبلیغات موبایلی گوگل را معرفی می‌کند.

کیت توسعه نرم‌افزار C++ تبلیغات موبایل گوگل (Google Mobile Ads C++ SDK) یک سطح API جدید است که تغییرات اساسی ایجاد شده در کیت‌های توسعه نرم‌افزار C++ فایربیس AdMob برای iOS و اندروید در سال‌های 2021 و 2022، از جمله حذف APIهای منسوخ شده و یک جریان جدید هنگام کار با انواع تبلیغات تمام صفحه را در خود جای داده است.

کیت توسعه نرم‌افزاری قدیمی Firebase AdMob C++ ( firebase::admob ) منسوخ شده است و از این پس هیچ به‌روزرسانی یا رفع اشکالی دریافت نخواهد کرد.

هم کیت توسعه نرم‌افزاری جدید Google Mobile Ads C++ ( firebase::gma ) و هم کیت توسعه نرم‌افزاری قدیمی Firebase AdMob C++ ( firebase::admob ) در طول دوره منسوخ شدن Firebase AdMob C++ SDK، همچنان بخشی از آرشیوهای ساخت‌شده برای Firebase C++ SDK باقی خواهند ماند.

حذف API قدیمی

APIهای زیر به طور کامل از کیت توسعه نرم‌افزار C++ تبلیغات موبایلی گوگل حذف شده‌اند.

RewardedVideoAd

فضای نام RewardedVideoAd در AdMob با کلاس RewardedAd جایگزین شده است. RewardedAd رفتاری مشابه InterstitialAd دارد اما شامل یک RewardedAdListener اضافی برای دریافت اعلان‌های مربوط به جوایز آیتم‌ها است.

NativeExpressAds

NativeExpressAd مربوط به AdMob قبلاً در هر کیت توسعه نرم‌افزاری Firebase AdMob C++ به عنوان منسوخ‌شده علامت‌گذاری شده بود. بنابراین NativeExpressAd در کیت توسعه نرم‌افزاری جدید Google Mobile Ads C++ گنجانده نشده است.

تغییر فضای نام SDK

SDK به یک فضای نام جدید منتقل شده است و ساختار دایرکتوری جدیدی دارد:

فضای نام firebase::gma

منابع کیت توسعه نرم‌افزاری جدید تبلیغات موبایلی گوگل (Google Mobile Ads C++ SDK) در فضای نام firebase::gma قرار دارند. فضای نام قدیمی‌تر firebase::admob به همراه کیت توسعه نرم‌افزاری Firebase AdMob C++ منسوخ شده است.

ساختار دایرکتوری

فایل‌های هدر به یک دایرکتوری جدید در داخل آرشیو ساخت منتقل شده‌اند:

کتابخانه

کیت توسعه نرم‌افزاری Firebase AdMob C++ به عنوان یک کتابخانه استاتیک در آرشیو ساخت کیت توسعه نرم‌افزاری Firebase C++ ارائه خواهد شد:

مهاجرت‌های کلاس، enum و struct

جدول زیر کلاس‌ها، enumها و structهای خاصی را که تغییر یافته یا حذف شده‌اند، فهرست می‌کند. خلاصه‌ای از آنها در اینجا آمده است:

• نام BannerView به AdView تغییر یافت.
• NativeAdExpressView حذف شده است.
• فضای نام RewardedVideo با کلاس RewardedAd جایگزین شده است.
• شمارشگر PresentationState و شنوندگان آن حذف شده و با شنوندگان AdListener و FullScreenContent جایگزین می‌شوند.

• پارامترهای زیر به عنوان پارامترهای پیکربندی هر تبلیغ در AdRequests حذف می‌شوند:

  • پیکربندی شناسه‌های دستگاه تست
  • هدف‌گیری تبلیغات بر اساس سن

  در عوض، این پارامترها اکنون می‌توانند در RequestConfiguration پیکربندی شوند که یک تنظیم سراسری است و بر تمام بارگذاری‌های بعدی تبلیغات تأثیر می‌گذارد.

مقداردهی اولیه SDK

هر تابع مقداردهی اولیه SDK مربوط به تبلیغات موبایلی گوگل (Google Mobile Ads) در زبان برنامه‌نویسی سی‌پلاس‌پلاس (C++) بلافاصله دو نشانگر وضعیت را برمی‌گرداند:

• یک پارامتر اختیاری out مشخص می‌کند که آیا قبل از شروع فرآیند مقداردهی اولیه، خطای وابستگی رخ داده است یا خیر.

• پارامتر برگشتی ارجاعی به یک firebase::Future است. Future شامل نتایج مقداردهی اولیه ناهمزمان آداپتورهای میانجیگری روی دستگاه است.

اگرچه ممکن است به محض بازگشت تابع مقداردهی اولیه، کیت توسعه نرم‌افزار 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 (که قبلاً توسط birth date مدیریت می‌شدند) از AdRequest حذف شده‌اند و اکنون بخشی از RequestConfiguration سراسری هستند. برنامه‌ها ممکن است در اوایل چرخه حیات برنامه، firebase::gma::SetRequestConfiguration() را برای پیکربندی این مقادیر فراخوانی کنند. تمام عملیات بارگذاری تبلیغات بعدی، پس از پیکربندی، این تنظیمات را رعایت خواهند کرد.

firebase::gma::AdRequest هنوز وجود دارد زیرا اطلاعات زمینه‌ای برای بارگیری تبلیغات، از جمله کلمات کلیدی و یک URL محتوای اختیاری، را ارائه می‌دهد.

ساختار AdRequest به سبک C در 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 Mobile Ads

نوع شمارشی firebase::admob::BannerView::PresentationState و متد شنونده OnPresentationStateChanged در SDK جدید C++ Ads گوگل موبایل گنجانده نشده‌اند.

روش‌های جایگزین زیر برای تشخیص تغییرات وضعیت نمایش در چرخه حیات یک AdView وجود دارد:

RewardedAd اکنون یک کلاس است

کیت توسعه نرم‌افزاری منسوخ‌شده‌ی Firebase AdMob C++، تبلیغات پاداشی را از طریق مجموعه‌ای از توابع در فضای نام firebase::admob::rewarded_ad تسهیل می‌کرد. این توابع در یک کلاس جدید RewardedAd ادغام شده‌اند که تبلیغاتی با سطح API مشابه InterstitialAd ارائه می‌دهد (به بخش بعدی مراجعه کنید).

شنوندگان InterstitialAd و RewardedAd

هم تبلیغات بینابینی و هم تبلیغات جایزه‌دار، تبلیغات تمام صفحه محسوب می‌شوند. می‌توان یک FullScreenContentListener جدید نصب کرد تا به رویدادهای چرخه عمر تبلیغات برای این نوع تبلیغات گوش دهد و یک PaidEventListener جداگانه نیز می‌توان نصب کرد تا زمانی که سرویس AdMob یک رویداد پولی را رخ داده است، ردیابی کند.

RewardedAd یک شنونده اضافی برای نظارت بر رویدادهای پاداش کسب شده توسط کاربر دارد.

روش‌های جدید فراخوانی تبلیغات تمام صفحه

روش‌ها تغییر/حذف/جایگزین شدند

جدول زیر روش‌های خاص تغییر یافته در SDK جدید تبلیغات موبایلی گوگل (Google Mobile Ads C++ SDK) را فهرست می‌کند. روش‌هایی که پارامترهای آنها ذکر شده است، باقی می‌مانند اما امضای آنها تغییر کرده است.