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

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

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

وقتی برنامه‌تان آگهی بینابینی نشان می‌دهد، کاربران می‌توانند روی آگهی ضربه بزنند و ادامه دهند، یا آگهی را ببندند و به برنامه برگردند. این مطالعه موردی را بخوانید.

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

قبل‌از شروع

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

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

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

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

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

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

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

برای شروع پیش‌بارگیری آگهی‌ها، روش start را یک‌بار هنگام مقداردهی اولیه GMA Next-Gen SDK فراخوانی کنید. پس‌از فراخوانی روش 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)
  InterstitialAdPreloader.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);
  InterstitialAdPreloader.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 = InterstitialAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : InterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Interstitial ad recorded an impression.")
      }
    }
  ad.show(activity)
}

جاوا

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

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

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

  // Show the ad.
  ad.show(activity);
}

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

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

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

Kotlin

// Listen for ad events.
val ad = interstitialAd
if (ad == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.")
  return
}

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

    override fun onAdDismissedFullScreenContent() {
      // Interstitial ad did dismiss.
      interstitialAd = null
    }

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

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

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

جاوا

// Listen for ad events.
if (interstitialAd == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.");
  return;
}

interstitialAd.setAdEventCallback(
    new InterstitialAdEventCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Interstitial ad did show.
      }

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

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

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

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

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

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

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

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,
        ("Interstitial preload ad $preloadId failed to load with error: ${adError.message}"),
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "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, "Interstitial preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
InterstitialAdPreloader.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(
                "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, "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, "Interstitial preload ad " + preloadId + " is available");
      }
    };

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

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

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

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

Kotlin

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

جاوا

private boolean isAdAvailable(String adUnitId) {
  return InterstitialAdPreloader.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)
  InterstitialAdPreloader.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);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}

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

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

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

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

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

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

Kotlin

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

جاوا

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

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

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

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

Kotlin

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

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