تبلیغات با پاداش


تبلیغات جایزه‌دار به کاربران این امکان را می‌دهد که در ازای دریافت جوایز درون‌برنامه‌ای، با آنها تعامل داشته باشند. این راهنما به شما نشان می‌دهد که چگونه با استفاده از Google Mobile Ads C++ SDK، تبلیغات جایزه‌دار را در برنامه‌های اندروید و iOS ادغام کنید.

چند داستان موفقیت مشتری را بخوانید: مطالعه موردی ۱ ، مطالعه موردی ۲ .

پیش‌نیازها

همیشه با تبلیغات آزمایشی تست کنید

هنگام ساخت و آزمایش برنامه‌های خود، مطمئن شوید که از تبلیغات آزمایشی به جای تبلیغات زنده و تولیدی استفاده می‌کنید. عدم انجام این کار می‌تواند منجر به مسدود شدن حساب شما شود.

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

  • اندروید: ca-app-pub-3940256099942544/5224354917
  • iOS: ca-app-pub-3940256099942544/1712485313

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

برای اطلاعات بیشتر در مورد نحوه عملکرد تبلیغات آزمایشی SDK تبلیغات موبایل، به بخش تبلیغات آزمایشی مراجعه کنید.

پیاده‌سازی

مراحل اصلی برای ادغام تبلیغات جایزه‌دار عبارتند از:

  1. یک تبلیغ بارگذاری کنید.
  2. برای تماس‌های برگشتی ثبت‌نام کنید.
  3. تبلیغ را نمایش دهید و رویداد پاداش را مدیریت کنید.

پیکربندی یک RewardedAd

تبلیغات جایزه‌دار در اشیاء RewardedAd نمایش داده می‌شوند، بنابراین اولین قدم برای ادغام تبلیغات جایزه‌دار در برنامه شما، ایجاد و مقداردهی اولیه یک نمونه از RewardedAd است.

  1. هدر زیر را به کد C++ برنامه خود اضافه کنید:

     #include "firebase/gma/rewarded_ad.h"

  2. یک شیء RewardedAd را تعریف و نمونه‌سازی کنید:

     firebase::gma::RewardedAd* rewarded_ad;
 rewarded_ad = new firebase::gma::RewardedAd();

  3. نمونه RewardedAd را با استفاده از نمای والد خود که به نوع AdParent تبدیل شده است، مقداردهی اولیه کنید. نمای والد یک ارجاع JNI jobject به یک Activity اندروید یا یک اشاره‌گر به یک UIView iOS است.

    // my_ad_parent is a jobject reference to an Android Activity or
// a pointer to an iOS UIView.
firebase::gma::AdParent ad_parent =
  static_cast<firebase::gma::AdParent>(my_ad_parent);
firebase::Future<void> result = rewarded_ad->Initialize(ad_parent);

  4. به عنوان جایگزینی برای حفظ آینده به عنوان یک متغیر، می‌توانید به صورت دوره‌ای وضعیت عملیات مقداردهی اولیه را با فراخوانی InitializeLastResult() روی شیء RewardedAd بررسی کنید. این می‌تواند برای پیگیری فرآیند مقداردهی اولیه در حلقه بازی سراسری شما مفید باشد.

    // Monitor the status of the future in your game loop:
firebase::Future<void> result = rewarded_ad->InitializeLastResult();
if (result.status() == firebase::kFutureStatusComplete) {
  // Initialization completed.
  if(future.error() == firebase::gma::kAdErrorCodeNone) {
    // Initialization successful.
  } else {
    // An error has occurred.
  }
} else {
  // Initialization on-going.
}

برای اطلاعات بیشتر در مورد کار با firebase::Future ، به بخش «استفاده از Futures برای نظارت بر وضعیت تکمیل فراخوانی‌های متد» مراجعه کنید.

بارگذاری یک تبلیغ

بارگذاری یک تبلیغ با استفاده از متد LoadAd() روی یک شیء RewardedAd انجام می‌شود. متد load مستلزم آن است که شیء RewardedAd را مقداردهی اولیه کرده باشید و شناسه واحد تبلیغ خود و یک شیء AdRequest را داشته باشید. یک firebase::Future برگردانده می‌شود که می‌توانید از آن برای نظارت بر وضعیت و نتیجه عملیات بارگذاری استفاده کنید.

کد زیر نحوه بارگذاری یک تبلیغ را پس از مقداردهی اولیه موفقیت‌آمیز RewardedAd نشان می‌دهد:

firebase::gma::AdRequest ad_request;
firebase::Future<firebase::gma::AdResult> load_ad_result;
load_ad_result = rewarded_ad->LoadAd(rewarded_ad_unit_id, ad_request);

برای تماس‌های برگشتی ثبت‌نام کنید

برای دریافت اعلان‌های مربوط به نمایش تبلیغات پاداش‌دار و رویدادهای چرخه عمر، باید کلاس FullScreenContentListener ارث‌بری کنید. زیرکلاس سفارشی FullScreenContentListener شما می‌تواند از طریق متد RewardedAd::SetFullScreenContentListener() ثبت شود و در صورت نمایش موفقیت‌آمیز یا ناموفق تبلیغ و همچنین لغو آن، فراخوانی‌های مجدد دریافت خواهد کرد.

کد زیر نحوه‌ی بسط دادن کلاس و اختصاص دادن آن به تبلیغ را نشان می‌دهد:

  class ExampleFullScreenContentListener
      : public firebase::gma::FullScreenContentListener {

   public:
    ExampleFullScreenContentListener() {}

    void OnAdClicked() override {
      // This method is invoked when the user clicks the ad.
    }

    void OnAdDismissedFullScreenContent() override {
     // This method is invoked when the ad dismisses full screen content.
    }

    void OnAdFailedToShowFullScreenContent(const AdError& error) override {
      // This method is invoked when the ad failed to show full screen content.
      // Details about the error are contained within the AdError parameter.
    }

    void OnAdImpression() override {
      // This method is invoked when an impression is recorded for an ad.
    }

    void OnAdShowedFullScreenContent() override {
      // This method is invoked when the ad showed its full screen content.
    }
  };

  ExampleFullScreenContentListener* example_full_screen_content_listener =
    new ExampleFullScreenContentListener();
  rewarded_ad->SetFullScreenContentListener(example_full_screen_content_listener);

RewardedAd یک شیء یک‌بار مصرف است. این بدان معناست که وقتی یک تبلیغ جایزه‌دار نمایش داده می‌شود، دیگر نمی‌توان آن را نمایش داد. بهترین روش این است که یک تبلیغ جایزه‌دار دیگر را در متد OnAdDismissedFullScreenContent() از FullScreenContentListener خود بارگذاری کنید تا تبلیغ جایزه‌دار بعدی به محض بسته شدن تبلیغ قبلی شروع به بارگذاری کند.

نمایش تبلیغ و مدیریت رویداد پاداش

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

هنگام ارائه تبلیغ خود، باید یک شیء UserEarnedReward ارائه دهید تا پاداش را برای کاربر مدیریت کند.

کد زیر نحوه نمایش یک RewardedAd را نشان می‌دهد:

// A simple listener track UserEarnedReward events.
class ExampleUserEarnedRewardListener :
    public firebase::gma::UserEarnedRewardListener {
 public:
   ExampleUserEarnedRewardListener() { }

  void OnUserEarnedReward(const firebase::gma::AdReward& reward) override {
    // Reward the user!
  }
};

ExampleUserEarnedRewardListener* user_earned_reward_listener =
  new ExampleUserEarnedRewardListener();
firebase::Future<void> result = rewarded_ad->Show(user_earned_reward_listener);

سوالات متداول

آیا برای فراخوانی مقداردهی اولیه، مهلت زمانی وجود دارد؟
پس از 10 ثانیه، کیت توسعه نرم‌افزار C++ تبلیغات موبایل گوگل، تابع firebase::Future که توسط Initialize() برگردانده شده است را تکمیل می‌کند، حتی اگر یک شبکه میانجی هنوز مقداردهی اولیه را انجام نداده باشد.
اگر برخی از شبکه‌های میانجیگری هنگام دریافت پاسخ اولیه آماده نباشند، چه می‌شود؟

بهترین روش این است که تبلیغات پس از اتمام مقداردهی اولیه SDK بارگذاری شوند. حتی اگر یک شبکه میانجیگری آماده نباشد، SDK C++ تبلیغات موبایل گوگل همچنان از آن شبکه درخواست تبلیغ می‌کند. بنابراین اگر یک شبکه میانجیگری مقداردهی اولیه را پس از مهلت زمانی به پایان برساند، همچنان می‌تواند درخواست‌های تبلیغاتی آینده را در آن جلسه ارائه دهد.

شما می‌توانید با فراخوانی GetInitializationStatus() به نظرسنجی از وضعیت اولیه‌سازی همه آداپتورها در طول جلسه برنامه خود ادامه دهید.

چگونه بفهمم که چرا یک شبکه میانجیگری خاص آماده نیست؟

AdapterStatus.description() توضیح می‌دهد که چرا یک آداپتور آماده‌ی سرویس‌دهی به درخواست‌های تبلیغاتی نیست. برای مثالی از ثبت وضعیت آداپتور میانجیگری، به کد منبع برنامه‌ی شروع سریع نمونه‌ی ما در GitHub مراجعه کنید.

منابع اضافی

مثال در گیت‌هاب