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

پلاتفرم را انتخاب کنید: Android iOS Unity Flutter Android (Legacy)

آگهی‌های پاداش‌دار آگهی‌هایی هستند که کاربران می‌توانند در ازای دریافت پاداش‌های درون‌برنامه با آن‌ها تعامل داشته باشند. این راهنما نشان می‌دهد چگونه آگهی‌های پاداش‌دار را از Ad Manager در برنامه Flutter ادغام کنید.

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

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

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

  • /21775744923/example/rewarded

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

بار کردن آگهی

مثال زیر آگهی پاداش‌دار را بار می‌کند:

RewardedAd.load(
  adUnitId: "_adUnitId",
  request: const AdManagerAdRequest(),
  rewardedAdLoadCallback: RewardedAdLoadCallback(
    onAdLoaded: (RewardedAd ad) {
      // Called when an ad is successfully received.
      debugPrint('Ad was loaded.');
      // Keep a reference to the ad so you can show it later.
      _rewardedAd = ad;
    },
    onAdFailedToLoad: (LoadAdError error) {
      // Called when an ad request failed.
      debugPrint('Ad failed to load with error: $error');
    },
  ),
);

_adUnitId را با شناسه واحد آگهی خودتان جایگزین کنید.

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

بااستفاده از FullScreenContentCallback، می‌توانید به رویدادهای چرخه حیات گوش دهید، مثلاً وقتی آگهی نشان داده می‌شود یا بسته می‌شود. RewardedAd.fullScreenContentCallback را قبل‌از نمایش آگهی تنظیم کنید تا اعلان‌های این رویدادها را دریافت کنید. این مثال هر روش را پیاده‌سازی می‌کند و پیامی را در کنسول ثبت می‌کند:

ad.fullScreenContentCallback = FullScreenContentCallback(
  onAdShowedFullScreenContent: (ad) {
    // Called when the ad showed the full screen content.
    debugPrint('Ad showed full screen content.');
  },
  onAdFailedToShowFullScreenContent: (ad, err) {
    // Called when the ad failed to show full screen content.
    debugPrint('Ad failed to show full screen content with error: $err');
    // Dispose the ad here to free resources.
    ad.dispose();
  },
  onAdDismissedFullScreenContent: (ad) {
    // Called when the ad dismissed full screen content.
    debugPrint('Ad was dismissed.');
    // Dispose the ad here to free resources.
    ad.dispose();
  },
  onAdImpression: (ad) {
    // Called when an impression occurs on the ad.
    debugPrint('Ad recorded an impression.');
  },
  onAdClicked: (ad) {
    // Called when a click is recorded for an ad.
    debugPrint('Ad was clicked.');
  },
);

آگهی تصویری

RewardedAd به‌عنوان «برافزایی» در بالای همه محتوای برنامه نمایش داده می‌شود و به‌صورت ایستا قرار می‌گیرد؛ بنابراین، نمی‌توان آن را به درخت ابزاره Flutter اضافه کرد. با فراخوانی show() می‌توانید انتخاب کنید آگهی چه زمانی نشان داده شود. RewardedAd.show() یک OnUserEarnedRewardCallback می‌گیرد که وقتی کاربر پاداش می‌گیرد فراخوانده می‌شود. حتماً این مورد را پیاده‌سازی کنید و به کاربر برای تماشای آگهی پاداش دهید.

_rewardedAd?.show(
  onUserEarnedReward: (AdWithoutView ad, RewardItem rewardItem) {
    debugPrint('Reward amount: ${rewardItem.amount}');
  },
);

وقتی show() فراخوانده شود، Ad که به این روش نمایش داده شده است را نمی‌توان به‌صورت برنامه‌نویسی‌شده برداشت و به ورودی کاربر نیاز دارد. RewardedAd فقط یک‌بار می‌تواند نشان داده شود. فراخوانی‌های بعدی برای نمایش، onAdFailedToShowFullScreenContent را راه‌اندازی می‌کند.

وقتی دیگر به آگهی نیازی نیست، باید آن را دور انداخت. بهترین روش برای زمان فراخوانی dispose() در فراخوانی‌های برگشتی FullScreenContentCallback.onAdDismissedFullScreenContent و FullScreenContentCallback.onAdFailedToShowFullScreenContent است.

[اختیاری] اعتبارسنجی تماس‌های برگشتی درستی‌سنجی سمت سرور (SSV)

برنامه‌هایی که به داده‌های اضافی در بازخوانی‌های درستی‌سنجی سمت سرور نیاز دارند باید از ویژگی داده‌های سفارشی آگهی‌های پاداشی استفاده کنند. هر مقدار رشته‌ای که در شیء آگهی پاداش‌دار تنظیم شده باشد به پارامتر پُرسمان custom_data فراخوان SSV ارسال می‌شود. اگر مقدار داده سفارشی تنظیم نشده باشد، مقدار پارامتر پُرسمان custom_data در فراخوانی SSV وجود نخواهد داشت.

نمونه کد زیر نحوه تنظیم گزینه‌های SSV را پس‌از بار شدن آگهی پاداش‌دار نشان می‌دهد:

RewardedAd.load(
  adUnitId: "_adUnitId",
  request: AdManagerAdRequest(),
  rewardedAdLoadCallback: RewardedAdLoadCallback(
    onAdLoaded: (ad) {
      ServerSideVerificationOptions _options =
          ServerSideVerificationOptions(
            customData: 'SAMPLE_CUSTOM_DATA_STRING',
          );
      ad.setServerSideOptions(_options);
      _rewardedAd = ad;
    },
    onAdFailedToLoad: (error) {},
  ),
);

SAMPLE_CUSTOM_DATA_STRING را با داده‌های سفارشی‌تان جایگزین کنید.