بار کردن یک آگهی پاداش‌دار

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

این راهنما نحوه ادغام آگهی‌های پاداش‌دار در برنامه Android را توضیح می‌دهد.

قبل‌از شروع

پیش‌از ادامه دادن، کارهای زیر را انجام دهید:

  • GMA Next-Gen SDK را راه‌اندازی کنید.
  • از شناسه واحد آگهی پاداش‌دار آزمایشی /21775744923/example/rewarded استفاده کنید.
    • هنگام ساختن و آزمایش کردن برنامه‌تان، مطمئن شوید که از آگهی‌های آزمایشی به‌جای آگهی‌های زنده و تولیدی استفاده می‌کنید. اگر از شناسه واحد آگهی آزمایشی استفاده نکنید، Google می‌تواند حسابتان را تعلیق کند.
    • قبل‌از انتشار برنامه‌تان، این شناسه را با شناسه واحد آگهی‌تان جایگزین کنید.
    • برای جزئیات درباره آگهی‌های آزمایشی GMA Next-Gen SDK، به فعال کردن آگهی‌های آزمایشی مراجعه کنید.

بار کردن آگهی

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

Kotlin

// Load ads after you initialize MobileAds.
RewardedAd.load(
  AdRequest.Builder(adUnitId).build(),
  object : AdLoadCallback<RewardedAd> {
    override fun onAdLoaded(ad: RewardedAd) {
      // Rewarded ad loaded.
      rewardedAd = ad
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {
      // Rewarded ad failed to load.
      Log.e(TAG, "Rewarded ad failed to load: ${adError.message}")
      rewardedAd = null
    }
  },
)

جاوا

// Load ads after you initialize MobileAds.
RewardedAd.load(
    new AdRequest.Builder(adUnitId).build(),
    new AdLoadCallback<RewardedAd>() {
      @Override
      public void onAdLoaded(@NonNull RewardedAd ad) {
        // Rewarded ad loaded.
        rewardedAd = ad;
      }

      @Override
      public void onAdFailedToLoad(@NonNull LoadAdError adError) {
        // Rewarded ad failed to load.
        Log.e(TAG, "Rewarded ad failed to load: " + adError.getMessage());
        rewardedAd = null;
      }
    });

هنگام آزمایش، از شناسه واحد آگهی آزمایشی استفاده کنید: /21775744923/example/rewarded.

نمایش آگهی

برای نمایش آگهی پاداش‌دار، روش show را فراخوانی کنید. برای مدیریت رویدادهای پاداش، از شیء OnUserEarnedRewardListener استفاده کنید.

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

Kotlin

private fun showAd(rewardedAd: RewardedAd, activity: Activity) {
  // Show the ad.
  rewardedAd.show(
    activity,
    object : OnUserEarnedRewardListener {
      override fun onUserEarnedReward(rewardItem: RewardItem) {
        // User earned the reward.
        val rewardAmount = rewardItem.amount
        val rewardType = rewardItem.type
      }
    },
  )
}

جاوا

private void showAd(RewardedAd rewardedAd, Activity activity) {
  // Show the ad.
  rewardedAd.show(
      activity,
      new OnUserEarnedRewardListener() {
        @Override
        public void onUserEarnedReward(@NonNull RewardItem rewardItem) {
          // User earned the reward.
          int rewardAmount = rewardItem.getAmount();
          String rewardType = rewardItem.getType();
        }
      });
}

گوش دادن به رویدادهای آگهی

قبل‌از نمایش آگهی، به رویدادهای چرخه حیات آگهی گوش دهید. مثال زیر برگشت فراخوانی‌ها را برای رویدادهای آگهی ثبت می‌کند:

Kotlin

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = rewardedAd
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : RewardedAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // Rewarded ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // Rewarded ad did dismiss.
        rewardedAd = null
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // Rewarded ad failed to show.
        Log.e(TAG, "Rewarded ad failed to show: ${fullScreenContentError.message}")
      }

      override fun onAdImpression() {
        // Rewarded ad did record an impression.
      }

      override fun onAdClicked() {
        // Rewarded ad did record a click.
      }
    }
}

جاوا

private void listenToAdEvents() {
  // Listen for ad events.
  if (rewardedAd == null) {
    Log.e(TAG, "Rewarded ad is not ready yet.");
    return;
  }

  rewardedAd.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // Rewarded ad did dismiss.
          rewardedAd = null;
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            FullScreenContentError fullScreenContentError) {
          // Rewarded ad failed to show.
          Log.e(TAG, "Rewarded ad failed to show: " + fullScreenContentError.getMessage());
        }

        @Override
        public void onAdImpression() {
          // Rewarded ad did record an impression.
        }

        @Override
        public void onAdClicked() {
          // Rewarded ad did record a click.
        }
      });
}

اختیاری: اعتبارسنجی فراخوانی‌های درستی‌سنجی سمت سرور (SSV)

برای ارسال بافت کاربر و برنامه در فراخوان‌های بازگشتی درستی‌سنجی سمت سرور (SSV)، گزینه‌های درستی‌سنجی را قبل‌از نمایش آگهی در شیء آگهی تنظیم کنید. چون فراخوانی‌های برگشتی SSV بدون وضعیت جلسه از Google به سرور شما می‌رسند، رشته‌های اختیاری زیر را پیوست کنید. Google این رشته‌ها را بدون تغییر به‌عنوان پارامترهای پُرسمان امضاشده در فراخوانی SSV بازارسال می‌کند:

  • پارامتر پُرسمان user_id: کاربر را برای اعتباردهی شناسایی می‌کند، مثلاً شناسه حساب داخلی.
  • پارامتر پُرسمان custom_data: داده‌های برنامه را حمل می‌کند، مثل جایگاه پاداش، سطح بازی، یا عدد یک‌باراستفاده تولیدشده توسط سرور.

اگر مقداری تنظیم نکنید، Google آن پارامتر پُرسمان را از فراخوانی SSV حذف می‌کند.

مثال زیر داده‌های سفارشی را در شیء آگهی قبل‌از نمایش آگهی تنظیم می‌کند:

Kotlin

RewardedAd.load(
  context,
  AD_UNIT_ID,
  AdRequest.Builder().build(),
  object : RewardedAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedAd) {
      rewardedAd = ad
      val options =
        ServerSideVerificationOptions.Builder().setCustomData("SAMPLE_CUSTOM_DATA_STRING").build()
      rewardedAd?.setServerSideVerificationOptions(options)
    }
  },
)

جاوا

RewardedAd.load(
    context,
    AD_UNIT_ID,
    new AdRequest.Builder().build(),
    new RewardedAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedAd ad) {
        rewardedAd = ad;
        ServerSideVerificationOptions options =
            new ServerSideVerificationOptions.Builder()
                .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
                .build();
        rewardedAd.setServerSideVerificationOptions(options);
      }
    });

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

نکته کلیدی: پارامتر پُرسمان custom_data کدبندی درصدی شده است. قبل‌از تجزیه کردن مقدار، رشته را در سرورتان رمزگشایی نشانی وب کنید و امضای فراخوان را قبل‌از اعتماد کردن به پارامترهای پُرسمان user_id یا custom_data درستی‌سنجی کنید.