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

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

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

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

قبل‌از شروع

قبل‌از ادامه دادن، موارد زیر را انجام دهید:

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

آشنایی با پیش‌بارگذاری آگهی (نسخه بتا)

پیش‌بارکردن آگهی در GMA Next-Gen SDK بار کردن و ذخیره کردن آگهی در حافظه نهان را خودکار می‌کند.

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

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

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

برای شروع پیش‌بار کردن آگهی‌ها، روش start را یک‌بار در شروع برنامه فراخوانی کنید. پس‌از فراخوانی روش start، GMA Next-Gen SDK به‌طور خودکار آگهی‌ها را ازپیش بار می‌کند و درخواست‌های ناموفق را برای پیکربندی‌های ازپیش بارشده دوباره امتحان می‌کند.

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

Kotlin

private fun startPreloading(adUnitId: String) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)
}

جاوا

private void startPreloading(String adUnitId) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);
}

‫AD_UNIT_ID را با شناسه واحد آگهی‌تان جایگزین کنید.

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

آگهی ازپیش‌بارگذاری‌شده را دریافت و نمایش دهید

وقتی می‌خواهید آگهی نشان دهید، روش pollAd را فراخوانی کنید. ‫GMA Next-Gen SDK آگهی دردسترس را بازیابی می‌کند و آگهی بعدی را به‌طور خودکار در پس‌زمینه پیش‌بار می‌کند. اگر آگهی دردسترس نباشد، GMA Next-Gen SDK آگهی برنمی‌گرداند.

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

Kotlin

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = RewardedInterstitialAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded interstitial ad recorded an impression.")
      }
    }
  ad.show(activity) { rewardItem -> Log.d(TAG, "User earned reward: ${rewardItem.amount}") }
}

جاوا

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  final RewardedInterstitialAd ad = RewardedInterstitialAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.");
    return;
  }

  Log.d(TAG, "Rewarded interstitial ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Rewarded interstitial ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(
      activity,
      rewardItem -> {
        Log.d(TAG, "User earned reward: " + rewardItem.getAmount());
      });
}

تا زمانی که آماده نمایش آگهی هستید، از فراخوانی روش pollAd خودداری کنید. برای خواندن اطلاعات پاسخ آگهی بدون نمایش آن، خواندن اطلاعات پاسخ را ببینید.

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

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

Kotlin

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

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

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

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

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

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

جاوا

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

  rewardedInterstitialAd.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded interstitial ad did show.
        }

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

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

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

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

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

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

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

Kotlin

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

جاوا

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

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

اختیاری: گوش دادن به رویدادهای پیش‌بارگذاری

وقتی پیش‌بار کردن آگهی‌ها را شروع می‌کنید، برای رویدادهای پیش‌بار کردن ثبت‌نام کنید تا وقتی آگهی‌ها باموفقیت پیش‌بار شدند، پیش‌بار کردن ناموفق بود، یا حافظه نهان آگهی تمام شد، اعلان دریافت کنید.

مثال زیر نحوه ثبت‌نام برای رویدادهای آگهی پیش‌بارگذاری را نشان می‌دهد:

Kotlin

val preloadCallback =
  // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(
        TAG,
        "Rewarded interstitial preload ad $preloadId failed to load with error: ${adError.message}",
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded interstitial preload ad $preloadId is not available")
      // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
    }

    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
      Log.i(TAG, "Rewarded interstitial preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

جاوا

PreloadCallback preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded interstitial preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
        // [Optional] Get the error response info for additional details.
        // ResponseInfo responseInfo = adError.getResponseInfo();
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is not available");
        // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is available");
      }
    };
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

وقتی آگهی بار نمی‌شود، GMA Next-Gen SDK به‌طور خودکار آگهی‌ها را پیش‌بار می‌کند و درخواست‌های ناموفق را برای پیکربندی‌های پیش‌بارشده دوباره امتحان می‌کند.

اختیاری: بررسی دردسترس بودن آگهی

اگر نیاز دارید بدانید که آگهی دردسترس است یا نه، دردسترس بودن آگهی را بررسی کنید. مثال زیر بررسی می‌کند که آیا آگهی پیش‌بارشده دردسترس است یا خیر:

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return RewardedInterstitialAdPreloader.isAdAvailable(adUnitId)
}

جاوا

private boolean isAdAvailable(String adUnitId) {
  return RewardedInterstitialAdPreloader.isAdAvailable(adUnitId);
}

اختیاری: اندازه میان‌گیر را تنظیم کنید

اندازه بافر تعداد آگهی‌های پیش‌بارگذاری‌شده‌ای را که در حافظه نگهداری می‌شوند کنترل می‌کند. به‌طور پیش‌فرض، ‫Google اندازه بافر را بهینه‌سازی می‌کند تا بین مصرف حافظه و تأخیر در ارائه آگهی تعادل برقرار کند. می‌توانید اندازه میان‌گیری سفارشی تنظیم کنید تا تعداد آگهی‌های نگهداری‌شده در حافظه افزایش یابد. توصیه می‌کنیم اندازه بافر دو آگهی پیش‌بارگذاری‌شده باشد.

مثال زیر نحوه تنظیم اندازه میان‌گیر را نشان می‌دهد:

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)
}

جاوا

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);
}

محدودیت‌های پیش‌بار کردن حافظه نهان

‫GMA Next-Gen SDK محدودیت سراسری برنامه را برای تعداد کل آگهی‌های پیش‌بارگذاری‌شده در همه واحدهای آگهی و شناسه‌های پیش‌بارگذاری اعمال می‌کند:

  • محدودیت پیش‌فرض: Google حداکثر شش آگهی پیش‌بارگذاری‌شده را در حافظه نگه می‌دارد. این حد در همه قالب‌ها و شناسه‌های پیش‌بارگذاری مشترک است.
  • توصیه می‌کنیم برای هر شناسه پیش‌بارگذاری، اندازه بافر را روی دو تنظیم کنید.

اختیاری: توقف پیش‌بارگذاری آگهی‌ها

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

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

Kotlin

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  RewardedInterstitialAdPreloader.destroy(adUnitId)
}

جاوا

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  RewardedInterstitialAdPreloader.destroy(adUnitId);
}

اختیاری: خواندن اطلاعات پاسخ

اطلاعات پاسخ آگهی پیش‌بارشده بعدی را بدون برداشتن آگهی از حافظه نهان بخوانید.

مثال زیر نحوه خواندن اطلاعات پاسخ آگهی پیش‌بارگذاری‌شده بعدی را نشان می‌دهد:

Kotlin

val responseInfo = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

جاوا

ResponseInfo responseInfo = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());