آگهی‌های پاداش‌دار


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

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

پیش‌نیازها

همیشه با آگهی‌های آزمایشی آزمایش کنید

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

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

  • ‫Android: ca-app-pub-3940256099942544/5224354917
  • ‫iOS: ‏ ca-app-pub-3940256099942544/1712485313

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

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

پیاده‌سازی

مراحل اصلی برای ادغام آگهی‌های پاداش‌دار عبارت‌اند از:

  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 به Android Activity یا اشاره‌گری به iOS UIView است.

    // 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، به استفاده از «آتی» برای نظارت بر وضعیت تکمیل تماس‌های روش مراجعه کنید.

بار کردن آگهی

بار کردن آگهی بااستفاده از روش LoadAd() در یک RewardedAd شیء انجام می‌شود. روش بار کردن نیازمند این است که 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);

پرسشگان

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

روال مطلوب این است که آگهی‌ها را پس‌از تکمیل مقداردهی اولیه «کیت توسعه نرم‌افزار» بار کنید. حتی اگر شبکه واسطه‌گری آماده نباشد، «کیت توسعه نرم‌افزار Google Mobile Ads C++» همچنان از آن شبکه آگهی درخواست خواهد کرد. بنابراین اگر شبکه واسطه‌گری پس‌از اتمام زمان راه‌اندازی اولیه، همچنان بتواند درخواست‌های آگهی آینده را در آن جلسه ارائه دهد.

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

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

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

منابع بیشتر

مثال در GitHub