انتقال به پیش‌بارگیری آگهی

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

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

پیش‌نیازها

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

درخواست آگهی با پیش‌بار کردن آگهی

در بار کردن تکی، برای هر درخواست آگهی، یک آگهی درخواست می‌کنید. با پیش‌بارگیری آگهی، پیش‌بارگذار را یک‌بار با شناسه پیش‌بارگیری و پیکربندی پیش‌بارگیری شروع می‌کنید.

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

Kotlin

بار کردن تکی:

// Request a single ad.
val adRequest = AdRequest.Builder(adUnitId).build()
InterstitialAd.load(adRequest, adLoadCallback)

پیش‌بارگیری آگهی:

// Start the preloader once with a preload configuration.
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
InterstitialAdPreloader.start(adUnitId, preloadConfig)

جاوا

بار تکی:

// Request a single ad.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
InterstitialAd.load(adRequest, adLoadCallback);

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

// Start the preloader once with a preload configuration.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
InterstitialAdPreloader.start(adUnitId, preloadConfig);

رفتن به کارگزارهای پیش‌بارگذاری

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

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

Kotlin

بار کردن تکی:

// Listen for single ad request load results.
val adLoadCallback =
  object : AdLoadCallback<InterstitialAd> {
    override fun onAdLoaded(ad: InterstitialAd) {
      // Ad loaded for a single request.
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {
      Log.d(TAG, "Ad failed to load: ${adError.message}")
    }
  }

InterstitialAd.load(adRequest, adLoadCallback)

پیش‌بارگیری آگهی:

// Observe cache updates across multiple ads.
val preloadCallback =
  object : PreloadCallback {
    override fun onAdPreloaded(
      preloadId: String,
      responseInfo: ResponseInfo,
    ) {
      // Ad preloaded into the cache and is ready to show.
    }

    override fun onAdFailedToPreload(
      preloadId: String,
      adError: LoadAdError,
    ) {
      Log.d(TAG, "Ad failed to preload: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      // All preloaded ads in the cache have been shown.
      Log.d(TAG, "Ads exhausted for: $preloadId")
    }
  }

InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

جاوا

بار تکی:

// Listen for single ad request load results.
AdLoadCallback<InterstitialAd> adLoadCallback =
    new AdLoadCallback<InterstitialAd>() {
      @Override
      public void onAdLoaded(@NonNull InterstitialAd ad) {
        // Ad loaded for a single request.
      }

      @Override
      public void onAdFailedToLoad(@NonNull LoadAdError adError) {
        Log.d(TAG, "Ad failed to load: " + adError.getMessage());
      }
    };

InterstitialAd.load(adRequest, adLoadCallback);

پیش‌بارگیری آگهی:

// Observe cache updates across multiple ads.
PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdPreloaded(
          @NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        // Ad preloaded into the cache and is ready to show.
      }

      @Override
      public void onAdFailedToPreload(
          @NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(TAG, "Ad failed to preload: " + adError.getMessage());
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        // All preloaded ads in the cache have been shown.
        Log.d(TAG, "Ads exhausted for: " + preloadId);
      }
    };

InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

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

نمایش آگهی‌ها از حافظه پنهان

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

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

Kotlin

بار کردن تکی:

// Retrieve the ad from a saved variable.
val interstitialAd = this.interstitialAd ?: return
// Display the ad.
interstitialAd.show(activity)

پیش‌بارگیری آگهی:

// Retrieve the ad directly from the preloader cache.
val interstitialAd = InterstitialAdPreloader.pollAd(adUnitId) ?: return
// Display the ad.
interstitialAd.show(activity)

جاوا

بار تکی:

// Retrieve the ad from a saved variable.
InterstitialAd interstitialAd = this.interstitialAd;
if (interstitialAd == null) {
  return;
}
// Display the ad.
interstitialAd.show(activity);

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

// Retrieve the ad directly from the preloader cache.
InterstitialAd interstitialAd = InterstitialAdPreloader.pollAd(adUnitId);
if (interstitialAd == null) {
  return;
}
// Display the ad.
interstitialAd.show(activity);

برداشتن ذخیره موقت دستی و بار کردن مجدد

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

الگوهای زیر را از کدتان بردارید:

  • ذخیره متغیر عضو در حافظه نهان: متغیرهای عضو را که اشیای آگهی را ذخیره می‌کنند حذف کنید.
  • بار کردن مجدد دستی: پس‌از اینکه کاربر آگهی را بست یا آگهی نشان داده نشد، فراخوانی‌های بار کردن را حذف کنید.
  • زمان‌سنج‌های سفارشی برای تلاش مجدد: کنترل‌کننده‌های تلاش مجدد، حلقه‌های پس‌گرد، و زمان‌سنج‌ها را حذف کنید. ‫GMA Next-Gen SDK تلاش مجدد برای درخواست‌های پیش‌بارگذاری به‌طور خودکار ناموفق بود.

مقایسه نمونه‌های کامل

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

Kotlin

بار کردن تکی:

// 1. Maintain a member variable to store the ad.
private var interstitialAd: InterstitialAd? = null

// 2. Load the ad and listen for load completion.
private fun loadAd() {
  val adRequest = AdRequest.Builder(adUnitId).build()
  InterstitialAd.load(
    adRequest,
    object : AdLoadCallback<InterstitialAd> {
      override fun onAdLoaded(ad: InterstitialAd) {
        interstitialAd = ad
      }

      override fun onAdFailedToLoad(adError: LoadAdError) {
        interstitialAd = null
      }
    },
  )
}

// 3. Show the saved ad.
private fun showAd(activity: Activity) {
  val interstitialAd = this.interstitialAd ?: return
  interstitialAd.adEventCallback =
    object : InterstitialAdEventCallback {
      override fun onAdDismissedFullScreenContent() {
        // Reload the ad after dismissal in single-load integrations.
        loadAd()
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError,
      ) {
        Log.d(TAG, "Ad failed to show: ${fullScreenContentError.message}")
      }
    }
  interstitialAd.show(activity)
}

پیش‌بارگیری آگهی:

// 1. Start preloading with a callback to listen for loaded ads.
private fun startPreloading(adUnitId: String) {
  val preloadCallback =
    object : PreloadCallback {
      override fun onAdPreloaded(
        preloadId: String,
        responseInfo: ResponseInfo,
      ) {
        // Ad preloaded successfully.
      }

      override fun onAdFailedToPreload(
        preloadId: String,
        adError: LoadAdError,
      ) {
        Log.d(TAG, "Ad failed to preload: ${adError.message}")
      }
    }

  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)
}

// 2. Show the ad immediately after polling.
private fun showAd(activity: Activity, adUnitId: String) {
  val interstitialAd = InterstitialAdPreloader.pollAd(adUnitId) ?: return
  interstitialAd.adEventCallback =
    object : InterstitialAdEventCallback {
      override fun onAdDismissedFullScreenContent() {
        // Preloading automatically fetches a replacement ad.
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError,
      ) {
        Log.d(TAG, "Ad failed to show: ${fullScreenContentError.message}")
      }
    }
  interstitialAd.show(activity)
}

جاوا

بار تکی:

// 1. Maintain a member variable to store the ad.
private InterstitialAd interstitialAd;

// 2. Load the ad and listen for load completion.
private void loadAd() {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  InterstitialAd.load(
      adRequest,
      new AdLoadCallback<InterstitialAd>() {
        @Override
        public void onAdLoaded(@NonNull InterstitialAd ad) {
          interstitialAd = ad;
        }

        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError adError) {
          interstitialAd = null;
        }
      });
}

// 3. Show the saved ad.
private void showAd(Activity activity) {
  if (interstitialAd == null) {
    return;
  }
  interstitialAd.setAdEventCallback(
      new InterstitialAdEventCallback() {
        @Override
        public void onAdDismissedFullScreenContent() {
          // Reload the ad after dismissal in single-load integrations.
          loadAd();
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          Log.d(
              TAG,
              "Ad failed to show: " + fullScreenContentError.getMessage());
        }
      });
  interstitialAd.show(activity);
}

پیش‌بارگیری آگهی:

// 1. Start preloading with a callback to listen for loaded ads.
private void startPreloading(String adUnitId) {
  PreloadCallback preloadCallback =
      new PreloadCallback() {
        @Override
        public void onAdPreloaded(
            @NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
          // Ad preloaded successfully.
        }

        @Override
        public void onAdFailedToPreload(
            @NonNull String preloadId, @NonNull LoadAdError adError) {
          Log.d(TAG, "Ad failed to preload: " + adError.getMessage());
        }
      };

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

// 2. Show the ad immediately after polling.
private void showAd(Activity activity, String adUnitId) {
  InterstitialAd interstitialAd = InterstitialAdPreloader.pollAd(adUnitId);
  if (interstitialAd == null) {
    return;
  }
  interstitialAd.setAdEventCallback(
      new InterstitialAdEventCallback() {
        @Override
        public void onAdDismissedFullScreenContent() {
          // Preloading automatically fetches a replacement ad.
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          Log.d(
              TAG,
              "Ad failed to show: " + fullScreenContentError.getMessage());
        }
      });
  interstitialAd.show(activity);
}

مراحل بعدی

برای پیکربندی ویژگی‌های پیش‌بارگیری، ادغام قالب‌های آگهی، و آزمایش پیاده‌سازی‌تان، منابع زیر را کاوش کنید: