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

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

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

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

قبل‌از شروع

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

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

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

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

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

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

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

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

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

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig)

جاوا

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.start(adUnitId, preloadConfig);

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

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

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

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

قبل‌از نمایش آگهی، روش pollAd را فراخوانی کنید. شیء آگهی پیش‌بارشده را ذخیره نکنید. وقتی روش 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 = RewardedAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded 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 RewardedAd ad = RewardedAdPreloader.pollAd(adUnitId);

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

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

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

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

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

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

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 درستی‌سنجی کنید.

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

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

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

Kotlin

val preloadCallback =
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(TAG, "Rewarded preload ad $preloadId failed to load with error: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded preload ad $preloadId is not available")
    }

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

جاوا

PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
      }

      @Override
      public void onAdsExhausted(String preloadId) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is not available");
      }

      @Override
      public void onAdPreloaded(String preloadId, ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is available");
      }
    };

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

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

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

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

Kotlin

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

جاوا

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

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

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

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

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
RewardedAdPreloader.start(adUnitId, preloadConfig)

جاوا

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);
RewardedAdPreloader.start(adUnitId, preloadConfig);

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

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

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

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

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

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

Kotlin

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

جاوا

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

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

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

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

Kotlin

val responseInfo = RewardedAdPreloader.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 = RewardedAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

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