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

اختيار المنصة: Android iOS Unity Android (إصدار قديم)

ميزة "التحميل المسبق للإعلانات" هي ميزة تديرها Google لتحميل الإعلانات في GMA Next-Gen SDK التي تتولّى تحميل الإعلانات وتخزينها مؤقتًا نيابةً عنك. تتطلّب ميزة "التحميل المسبق للإعلانات" تغيير طريقة إدارة تحميل الإعلانات. لتحسين الأداء باستخدام ميزة "التحميل المسبق للإعلانات"، عليك إيقاف التخزين المؤقت المخصّص وتفويض هذه المسؤولية إلى GMA Next-Gen SDK.

تقدّم ميزة "التحميل المسبق للإعلانات" المزايا التالية مقارنةً بتحميل الإعلانات يدويًا:

  • إدارة المراجع: تحتفظ هذه الميزة بالإعلانات التي تم تحميلها حتى تصبح جاهزًا لعرضها، ما يغنيك عن الاحتفاظ بالمراجع.
  • إعادة التحميل التلقائي: يتم تحميل إعلان جديد تلقائيًا عند سحب إعلان من ذاكرة التخزين المؤقت.
  • إعادة المحاولة المُدارة: تتم إعادة محاولة الطلبات التي تعذّر إرسالها تلقائيًا باستخدام التراجع الدليلي.
  • التعامل مع انتهاء الصلاحية: يتم تلقائيًا إعادة تحميل الإعلانات قبل انتهاء صلاحيتها (عادةً بعد ساعة واحدة).
  • تحسين ذاكرة التخزين المؤقت: إذا كنت تستخدم حجم ذاكرة تخزين مؤقت أكبر من واحد، GMA Next-Gen SDK تعمل على تحسين ترتيب ذاكرة التخزين المؤقت لعرض أفضل إعلان.

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

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

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

  • اختياري: تنزيل تطبيق المثال وتشغيله

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

لبدء التحميل المسبق للإعلانات، عليك استدعاء الدالة startPreload(). لا تستدعِ هذه الطريقة إلا مرة واحدة لكل رقم تعريف تحميل مسبق. ننصحك باستدعاء الطريقة عند بدء جلسة التطبيق. بعد استدعاء الدالة startPreload()، GMA Next-Gen SDK تعمل تلقائيًا على التحميل المسبق للإعلانات وإعادة محاولة الطلبات التي تعذّر إرسالها لأرقام تعريف التحميل المسبق هذه.

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

Kotlin

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

جافا

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

الحصول على الإعلان الذي تم تحميله مسبقًا وعرضه

عند استخدام ميزة "التحميل المسبق للإعلانات"، تحتفظ GMA Next-Gen SDK بالإعلانات المخزّنة مؤقتًا. عندما تريد عرض إعلان، عليك استدعاء الدالة pollAd(). GMA Next-Gen SDK تستردّ الإعلان المتاح وتحمّل تلقائيًا الإعلان التالي مسبقًا في الخلفية.

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

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)
  }
}

جافا

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);
  }
}

الحصول على البيانات الوصفية للإعلان الذي تم تحميله مسبقًا

للحصول على البيانات الوصفية للإعلان الذي تم تحميله مسبقًا، يمكنك البحث عن عنصر معلومات استجابة الإعلان. تتيح لك هذه العملية فحص البيانات الوصفية للإعلان بدون إزالتها من ذاكرة التخزين المؤقت.

يبحث المثال التالي عن البيانات الوصفية لإعلان تم تحميله مسبقًا من عنصر معلومات الاستجابة:

Kotlin

private fun peekAdResponseInfo(preloadId: String) {
  InterstitialAdPreloader.peekAdResponseInfo(preloadId)?.let {
    Log.d(TAG, "Peeked ad response ID: ${it.responseId}")
  }
}

جافا

private void peekAdResponseInfo(String preloadId) {
  ResponseInfo responseInfo = InterstitialAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo != null) {
    Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());
  }
}

التحقّق من توفّر ميزة "التحميل المسبق للإعلانات"

للتحقّق من توفّر الإعلانات، اختَر أحد الخيارَين التاليَين:

الحصول على معلومات حول توفّر ميزة "التحميل المسبق للإعلانات"

يتحقّق المثال التالي من توفّر الإعلانات:

Kotlin

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

جافا

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

الاستماع إلى معلومات حول توفّر ميزة "التحميل المسبق للإعلانات"

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

أحداث التحميل المسبق مخصّصة لأغراض الإحصاءات. ضمن عمليات معاودة الاتصال لأحداث التحميل المسبق:

  • لا تستدعِ الدالة startPreload().
  • تجنَّب استدعاء الدالة pollAd() إلا إذا كان سيتم عرض الإعلان على الفور.

يسجِّل المثال التالي أحداث الإعلانات:

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")
        // [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)
}

جافا

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");
          // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
        }

        @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);
}

إيقاف التحميل المسبق للإعلانات

إذا لم تعُد بحاجة إلى عرض الإعلانات لرقم تعريف تحميل مسبق معيّن في الجلسة، يمكنك إيقاف التحميل المسبق للإعلانات. لإيقاف التحميل المسبق للإعلانات لرقم تعريف تحميل مسبق معيّن، عليك استدعاء الدالة destroy() باستخدام رقم تعريف التحميل المسبق. لإيقاف التحميل المسبق لجميع أدوات التحميل المسبق، عليك استدعاء الدالة destroyAll().

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

يتحكّم حجم ذاكرة التخزين المؤقت في عدد الإعلانات التي يتم تحميلها مسبقًا والاحتفاظ بها في الذاكرة. تُحسِّن Google تلقائيًا حجم ذاكرة التخزين المؤقت لتحقيق التوازن بين استهلاك الذاكرة والمدة المستغرقة لعرض الإعلانات. إذا كان تطبيقك يعرض الإعلانات قبل تحميل الإعلان التالي، يمكنك ضبط حجم ذاكرة تخزين مؤقت مخصّص لزيادة عدد الإعلانات المحتفظ بها في الذاكرة. ننصحك باستخدام حجم ذاكرة تخزين مؤقت يبلغ اثنين أو ثلاثة.

حدود ذاكرة التخزين المؤقت للتحميل المسبق

GMA Next-Gen SDK تفرض حدًا على مستوى التطبيق بالكامل لإجمالي عدد الإعلانات التي يتم تحميلها مسبقًا على مستوى جميع الوحدات الإعلانية وأرقام تعريف التحميل المسبق:

  • الحدّ التلقائي: GMA Next-Gen SDK تحتفظ بحد أقصى ستة إعلانات تم تحميلها مسبقًا في الذاكرة. تتم مشاركة هذا الحدّ على مستوى جميع الأشكال وأرقام تعريف التحميل المسبق.
  • ننصحك بالاحتفاظ بحجم ذاكرة تخزين مؤقت يبلغ اثنين أو ثلاثة لكل رقم تعريف تحميل مسبق.

Kotlin

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

جافا

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