این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

پیش نیازها

کامل شروع کنید .
(فقط اندروید) آشنایی با کار با مراجع JNI jobject (به نکات Android JNI مراجعه کنید).

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

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

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

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

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

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

پیاده سازی

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

یک تبلیغ را بارگیری کنید.
برای پاسخ به تماس ها ثبت نام کنید.
تبلیغ را نمایش دهید و رویداد پاداش را مدیریت کنید.

`RewardedAd` پیکربندی کنید

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

هدر زیر را به کد C++ برنامه خود اضافه کنید:
```
 #include "firebase/gma/rewarded_ad.h"
```

یک شی RewardedAd را اعلام و نمونه سازی کنید:

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

نمونه 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);
```
به عنوان جایگزینی برای حفظ آینده به عنوان یک متغیر، می توانید به صورت دوره ای وضعیت عملیات مقداردهی اولیه را با فراخوانی 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);

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

آیا مهلت زمانی برای تماس اولیه وجود دارد؟: پس از 10 ثانیه، Google Mobile Ads C++ SDK firebase::Future که توسط Initialize() برگردانده شده است، تکمیل می‌کند، حتی اگر یک شبکه میانجی هنوز راه‌اندازی اولیه را کامل نکرده باشد.
اگر برخی از شبکه‌های میانجی آماده نباشند، چه باید کرد؟: بارگذاری تبلیغات پس از تکمیل اولیه SDK بهترین روش است. حتی اگر شبکه میانجی آماده نباشد، Google Mobile Ads C++ SDK همچنان از آن شبکه برای آگهی درخواست می‌کند. بنابراین، اگر یک شبکه میانجی پس از اتمام زمان، شروع به کار کند، همچنان می‌تواند درخواست‌های تبلیغات آینده را در آن جلسه سرویس دهد.; می توانید با فراخوانی GetInitializationStatus() به بررسی وضعیت اولیه همه آداپتورها در طول جلسه برنامه خود ادامه دهید.
چگونه می توانم بفهمم که چرا یک شبکه میانجی خاص آماده نیست؟: AdapterStatus.description() توضیح می دهد که چرا یک آداپتور آماده سرویس دهی به درخواست های تبلیغاتی نیست. برای مثالی از وضعیت آداپتور میانجی ثبت‌نام، به کد منبع برنامه شروع سریع نمونه ما در GitHub مراجعه کنید.

منابع اضافی

مثال در GitHub

کد منبع برنامه شروع سریع نمونه ما را در GitHub مشاهده کنید.