انتقال به کیت توسعه نرم‌افزار جدید تبلیغات تلفن همراه Google برای ++C


انتشار Firebase C++ SDK v9.1.0 یک Google Mobile Ads C++ SDK جدید را معرفی می‌کند.

Google Mobile Ads C++ SDK یک سطح API جدید است که تغییرات عمده‌ای را که در Firebase AdMob C++ SDK برای iOS و Android در سال‌های ۲۰۲۱ و ۲۰۲۲ ایجاد شده است، ازجمله حذف APIهای منسوخ‌شده و جریان جدید هنگام کار با انواع آگهی‌های تمام‌صفحه، دربرمی‌گیرد.

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

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

برداشتن میانای برنامه‌سازی کاربردی قدیمی

میاناهای برنامه‌سازی کاربردی زیر به‌طور کامل از Google Mobile Ads C++ SDK برداشته شده‌اند.

RewardedVideoAd

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

NativeExpressAds

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

تغییر فضای نام کیت توسعه نرم‌افزار

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

فضای نام firebase::gma

منابع «کیت توسعه نرم‌افزار» جدید Google Mobile Ads C++‎ در فضای نام firebase::gma قرار دارند. فضای نام قدیمی‌تر firebase::admob به‌همراه کیت توسعه نرم‌افزار Firebase AdMob C++‎ منسوخ شده است.

ساختار فهرست راهنما

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

کیت توسعه نرم‌افزار Firebase AdMob C++‎ منسوخ‌شده کیت توسعه نرم‌افزار آگهی تلفن همراه Google جدید برای ++C
include/firebase/admob include/firebase/gma

کتابخانه

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

iOS

کیت توسعه نرم‌افزار Firebase AdMob C++‎ منسوخ‌شده کیت توسعه نرم‌افزار آگهی تلفن همراه Google جدید برای ++C
firebase_admob.xcframework firebase_gma.xcframework

Android

کیت توسعه نرم‌افزار Firebase AdMob C++‎ منسوخ‌شده کیت توسعه نرم‌افزار آگهی تلفن همراه Google جدید برای ++C
libfirebase_admob.a libfirebase_gma.a

انتقال کلاس، enum، و struct

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

  • نام BannerView به AdView تغییر کرد.
  • ‫NativeAdExpressView برداشته شد.
  • جای‌نام RewardedVideo با کلاس RewardedAd جایگزین شده است.
  • شمارش و شنوندگان PresentationState برداشته شده‌اند و شنوندگان AdListener و FullScreenContent جایگزین آن‌ها شده‌اند.
  • پارامترهای زیر به‌عنوان پارامترهای پیکربندی هر آگهی در AdRequests برداشته شده‌اند:

    • پیکربندی شناسه‌های دستگاه آزمایشی
    • هدف‌یابی آگهی‌ها براساس سن

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

firebase::admob namespace منسوخ‌شده firebase::gma namespace جدید
AdSizeType (enum) AdSize::Type (enum)
BannerView AdView
BannerView::Listener AdListener
AdViewBoundingBoxListener
PaidEventListener
BannerView::Position AdView::Position
BannerView::PresentationState برداشته شد
ChildDirectedTreatmentState RequestConfiguration::TagForChildDirectedTreatment
Gender (enum) برداشته شد
InterstitialAd::Listener FullScreenContentListener
PaidEventListener
KeyValuePair برداشته شد
NativeExpressAdView برداشته شد
PollableRewardListener برداشته شد
RewardItem AdReward
‫RewardedVideoAd (فضای نام) RewardedAd (کلاس)
RewardedVideoAd::Listener FullScreenContentListener
PaidEventListener
UserEarnedRewardListener
AdMobError (enum) AdErrorCode (enum)
RewardItem AdReward

مقداردهی اولیه کیت توسعه نرم‌افزار

هر تابع مقداردهی اولیه «کیت توسعه نرم‌افزار تبلیغات تلفن همراه Google» به زبان C++‎ فوراً دو نشانگر وضعیت را برمی‌گرداند:

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

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

While the Google Mobile Ads C++ SDK may be invoked to load AdMob-served ads as soon as the initialization function returns, other ad networks will not serve ads until their corresponding medation adapter has been fully initialized. این فرایند به‌صورت ناهمگام انجام می‌شود. بنابراین، اگر از میانجی‌گری آگهی در برنامه‌تان استفاده می‌کنید، توصیه می‌کنیم قبل‌از تلاش برای بار کردن آگهی، منتظر بمانید تا 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 که ارتفاع پویایی براساس عرض داده‌شده و جهت فعلی صفحه‌نمایش دارند پشتیبانی می‌کند.

ثابت‌های AdSize ایستا به firebase::gma::AdSize اضافه شد

AdSize::kBanner

اندازه آگهی برنمای «انجمن بازاریابی تلفن همراه» (MMA) (‏۳۲۰×۵۰ پیکسل مستقل از تراکم)

AdSize::kFullBanner

اندازه آگهی برنمای کامل «دفتر تبلیغات تعاملی» (IAB) (‏۴۶۸×۶۰ پیکسل مستقل از تراکم)
AdSize::kLargeBanner نسخه بلندتر kBanner، معمولاً ۳۲۰×۱۰۰

AdSize::kLeaderboard

اندازه آگهی تابلو پیشتازان «دفتر تبلیغات تعاملی» (IAB) (‏۷۲۸×۹۰ پیکسل مستقل از تراکم)
AdSize::kMediumRectangle اندازه آگهی مستطیل متوسط «دفتر تبلیغات تعاملی» (IAB) (۳۰۰×۲۵۰ پیکسل مستقل از تراکم)
روش‌های ایستا در firebase::gma::AdSize برای کمک به ساختن نمونه‌های AdSize
GetLandscapeAnchoredAdaptiveBannerAdSize یک AdSize با عرض داده‌شده و ارتفاع بهینه‌شده توسط Google ایجاد می‌کند تا یک آگهی برنمایشی در حالت افقی بسازد.
GetPortraitAnchoredAdaptiveBannerAdSize ‫AdSize را با عرض داده‌شده و ارتفاع بهینه‌سازی‌شده Google ایجاد می‌کند تا آگهی برنمایی در حالت عمودی ایجاد کند
GetCurrentOrientationAnchoredAdaptiveBannerAdSize یک AdSize با عرض داده‌شده و ارتفاع بهینه‌شده توسط Google ایجاد می‌کند تا یک آگهی بنری با توجه به جهت فعلی ایجاد کند.
GetInlineAdaptiveBannerAdSize AdSize مناسب‌ترین برای آگهی‌های برنمای داده‌شده را ایجاد می‌کند حداکثر ارتفاع

این AdSize به سرورهای Google اجازه می‌دهد اندازه آگهی بهینه را با ارتفاعی کمتر یا مساوی با حداکثر ارتفاع مشخص‌شده انتخاب کنند.

GetLandscapeInlineAdaptiveBannerAdSize InlineAdaptive AdSize با عرض داده‌شده و ارتفاع افقی دستگاه ایجاد می‌کند
GetPortraitInlineAdaptiveBannerAdSize InlineAdaptive AdSize با عرض داده‌شده و ارتفاع عمودی دستگاه ایجاد می‌کند.
GetCurrentOrientationInlineAdaptiveBannerAdSize روش راحتی برای برگرداندن InlineAdaptive AdSize با توجه به جهت فعلی میانجی با توجه به عرض خاص.

قبل

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 همچنان وجود دارد زیرا اطلاعات زمینه‌ای را برای بار کردن آگهی‌ها، ازجمله کلیدواژه‌ها و نشانی وب محتوای اختیاری، ارائه می‌دهد.

ساختار سبک C در AdRequest AdMob با کلاسی با روش‌هایی جایگزین شده است که تجربه کاربری بهتری را هنگام تعریف و افزودن به فهرست‌های مختلف اطلاعات ارائه می‌دهد.

تغییرات قابل‌توجه AdRequest در اینجا آمده است:

  • اکنون موارد اضافی با نام کلاس آداپتور میانجی مرتبط هستند. موارد اضافی ارسال‌شده به سرویس AdMob باید از نام کلاس پیش‌فرض به‌شرح زیر استفاده کند.
  • هنگام درخواست آگهی، برنامه‌ها ممکن است نشانی وب محتوایی را که ارائه می‌دهند ارسال کنند. این کار هدف‌یابی کلیدواژه را فعال می‌کند تا آگهی با محتوای دیگری که نمایش داده می‌شود مطابقت داشته باشد.

قبل

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++‎ جایگزین شده است:

  • AdListener چرخه حیات آگهی و رویدادهای تعامل کاربر را ردیابی می‌کند.
  • AdViewBoundingBoxListener زمانی فراخوانی می‌شود که AdView تغییر اندازه دهد یا جابه‌جا شود.

نگاشت‌های Google Mobile Ads پاسخ تماس OnPresentationStateChanged AdMob

نوع شمارشی firebase::admob::BannerView::PresentationState و روش شنونده OnPresentationStateChanged در کیت توسعه نرم‌افزار Google Mobile Ads C++‎ جدید گنجانده نشده‌اند.

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

firebase::admob::BannerView::Listener OnPresentationStateChanged رویداد ‫firebase::gma::AdListener همتا
kPresentationStateHidden وقتی AdListener::OnAdClosed فراخوانی می‌شود، یا وقتی AdView::Hide() عملیات ناهمگام خود را با موفقیت تکمیل می‌کند
kPresentationStateVisibleWithoutAd هیچ‌یک. تلاش برای فراخوانی AdView::Show() یک AdView بارنشده منجر به خطا خواهد شد.
kPresentationStateVisibleWithAd وقتی AdListener::OnAdOpened فراخوانده می‌شود، یا وقتی AdView::Show() عملیات ناهمگام خود را با موفقیت با آگهی تکمیل می‌کند
kPresentationStateOpenedPartialOverlay پس‌از فراخوانی AdListener::OnAdOpened()، چارگوش مرزی را جستجو کنید تا اندازه و موقعیت آگهی درحال نمایش را تعیین کنید. یا اینکه موقعیت AdView و AdSize را جستجو کنید و/یا چارگوش محدودکننده را ازطریق AdViewBoundingBoxListener پایش کنید.
kPresentationStateCoveringUI kPresentationStateOpenedPartialOverlay را در بالا ببینید

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

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

‫InterstitialAd و RewardedAd شنونده

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

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

روش‌های فراخوانی آگهی تمام‌صفحه جدید

FullScreenContentListener روش PaidEventListener روش UserEarnedRewardListener روش
OnAdClicked OnPaidEvent OnUserEarnedReward
OnAdDismissedFullScreenContent
OnAdFailedToShowFullScreenContent
OnAdImpression
OnAdShowedFullScreenContent

روش‌ها تغییر کرده/برداشته شده/جایگزین شده است

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

کلاس Firebase AdMob C++ SDK API Google Mobile Ads C++ SDK API یادداشت‌ها
BannerView MoveTo AdView::SetPosition
presentation_state برداشته شد با AdViewListener رویداد و AdView::Show و AdView::Hide نتیجه آینده رسیدگی شد.
SetListener AdView::SetAdListener
AdView::SetBoundingBoxListener
AdView::SetPaidEventListener
طراحی جدید شنونده، دقت تشخیص رویدادهای چرخه حیات AdView را افزایش می‌دهد.
Listener::OnPresentationStateChanged برداشته شد BannerView::SetListener را در بالا ببینید.
Listener::OnBoundingBoxChanged AdViewBoundingBoxListener::OnBoundingBoxChanged
InterstitialAd Initialize(AdParent parent, const char* ad_unit_id) Initialize(AdParent parent) پارامتر ad_unit_id اکنون بخشی از عملیات LoadAd است.
LoadAd(const AdRequest& request) LoadAd(const char* ad_unit_id, const AdRequest& request)
presentation_state برداشته شد شمارش presentation_state برداشته شده است. از FullScreenContentListener استفاده کنید.
SetListener SetFullScreenContentListener
SetPaidEventListener
Destroy برداشته شد پاک‌سازی منابع اکنون بخشی از تخریب‌کننده RewardedAd است.
RewardedAd
(رسماً
RewardedVideoAd)
Initialize Initialize(AdParent parent) AdParent قبلاً به Show منتقل شده بود، اما اکنون بخشی از مقداردهی اولیه است.
presentation_state برداشته شد شمارش presentation_state برداشته شده است. از FullScreenContentListener استفاده کنید.
SetListener SetFullScreenContentListener
SetPaidEventListener Show
هنگام نمایش RewardedAd، شنونده UserEarnedReward نیز تعریف می‌شود. در زیر ببینید.
Show(AdParent parent) Show(UserEarnedRewardListener* listener)