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


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

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

پیش‌نیازها

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

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

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

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

بار کردن آگهی

بار کردن آگهی بااستفاده از روش 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 Mobile Ads C++‎ firebase::Future برگردانده‌شده توسط Initialize() را تکمیل می‌کند، حتی اگر شبکه میانجی هنوز مقداردهی اولیه را تکمیل نکرده باشد.
اگر برخی‌از شبکه‌های میانجی هنگام دریافت فراخوانی برگشتی مقداردهی اولیه آماده نباشند چه می‌شود؟

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

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

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

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

منابع بیشتر

نمونه در GitHub