التحميل المُسبَق للإعلانات (إصدار تجريبي)

التحميل المُسبَق للإعلانات هو عملية تحميل وتخزين مؤقت تتم إدارتها من خلال حزمة SDK، وتلغي الحاجة إلى تحميل الإعلانات وتخزينها مؤقتًا يدويًا. تتيح لك هذه العملية عرض الإعلانات عند الحاجة بدون الحاجة إلى تحميل الإعلانات يدويًا أو التعامل مع عمليات معاودة الاتصال الخاصة بتحميل الإعلانات.

يتناول هذا الدليل كيفية ضبط إعدادات الإعلانات المحمَّلة مسبقًا والتحقّق من توفّرها، وكيفية الحصول على الإعلان المحمَّل مسبقًا وعرضه.

المتطلبات الأساسية

قبل المتابعة في هذا البرنامج التعليمي، عليك إكمال ما يلي:

  • ثبِّت الإصدار 0.14.0-alpha01 أو إصدارًا أحدث من حزمة تطوير البرامج (الإصدار التجريبي) "SDK لإعلانات Google على الأجهزة الجوّالة".
  • أكمِل دليل البدء.

بدء التحميل المُسبَق للإعلانات

لبدء التحميل المُسبَق، استدعِ الدالة startPreload(). تعيد حزمة تطوير البرامج "SDK لإعلانات Google على الأجهزة الجوّالة" تلقائيًا محاولة طلبات الإعلانات التي تعذّر تنفيذها للإعدادات المُحمَّلة مسبقًا.

يبدأ المثال التالي في التحميل المُسبَق للإعلانات:

Kotlin

private fun startPreloading(adUnitID: String) {
  val adRequest: AdRequest = AdRequest.Builder(adUnitID).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  InterstitialAdPreloader.start(adUnitID, preloadConfig)
}

Java

private void startPreloading(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}

اختياري: تعديل الإعلانات التي يتم تحميلها مسبقًا

لتغيير الإعلانات التي يتم تحميلها مسبقًا، استدعِ الدالة destroy()، ثم استدعِ الدالة startPreload() مرة أخرى مع التهيئة المعدَّلة.

اختياري: إيقاف التحميل المُسبَق للإعلانات

لإيقاف التحميل المُسبَق للإعلانات، استخدِم destroy() مع معرّف التحميل المُسبَق.

اختياري: ضبط حجم ذاكرة التخزين المؤقت

يتحكّم حجم المخزن المؤقت في عدد الإعلانات المحمَّلة مسبقًا والمخزَّنة في الذاكرة. إذا كان تطبيقك يعرض الإعلانات بشكل أسرع من سرعة تحميل الإعلانات الجديدة، اضبط حجم المخزن المؤقت على قيمة أكبر. إذا كنت قلقًا بشأن استخدام الذاكرة، اضبط حجم المخزن المؤقت على قيمة منخفضة، مثل 2.

Kotlin

private fun setBufferSize(adUnitID: String) {
  val adRequest: AdRequest = AdRequest.Builder(adUnitID).build()
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 3)
  InterstitialAdPreloader.start(adUnitID, preloadConfig)
}

Java

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 3);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}

اختياري: تلقّي إشعارات بشأن التحميل المُسبَق

نفِّذ PreloadCallback لتلقّي إشعارات بشأن أحداث التحميل المُسبَق للإعلانات. لتصحيح الأخطاء وتسجيلها، تقدّم هذه الأحداث عنصر response info.

Kotlin

private fun startPreloadingWithCallback(adUnitID: String) {
  val preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    object : PreloadCallback {
      override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
        Log.i(
          TAG,
          ("Interstitial preload ad $preloadId failed to load with error: ${adError.message}"),
        )
        // [Optional] Get the error response info for additional details.
        // val responseInfo = adError.responseInfo
      }

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

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

Java

private void startPreloadingWithCallback(String adUnitId) {
  PreloadCallback preloadCallback =
      // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
      new PreloadCallback() {
        @Override
        public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
          Log.e(
              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(String preloadId) {
          Log.i(TAG, "Interstitial preload ad " + preloadId + " is not available");
        }

        @Override
        public void onAdPreloaded(String preloadId, 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);
}

الحصول على الإعلان المحمَّل مسبقًا وعرضه

تتوفّر الإعلانات للعرض بعد استدعاء onAdsAvailable(). تتوفّر الإعلانات باستمرار عند عرضها واستنفادها. بعد تلقّي إعلان، استمِع إلى أحداث مراحل نشاط الإعلان واعرض الإعلان.

يوضّح المثال التالي إعلانًا تم تحميله مسبقًا:

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)

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

        override fun onAdPaid(value: AdValue) {
          Log.d(TAG, "Interstitial ad onPaidEvent: ${value.valueMicros} ${value.currencyCode}")
        }
      }

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

Java

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.d(TAG, "Interstitial ad response info: " + ad.getResponseInfo());
    ad.setAdEventCallback(
        new InterstitialAdEventCallback() {
          @Override
          public void onAdImpression() {
            Log.d(TAG, "Interstitial ad recorded an impression.");
          }

          @Override
          public void onAdPaid(AdValue value) {
            Log.d(
                TAG,
                "Interstitial ad onPaidEvent: "
                    + value.getValueMicros()
                    + " "
                    + value.getCurrencyCode());
          }
        });

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

اختياري: التحقّق من توفّر الإعلانات المحمَّلة مسبقًا

لمعرفة ما إذا كانت الإعلانات متاحة، اتّصِل بالرقم isAdAvailable:

Kotlin

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

Java

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