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

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

ميزة "التحميل المُسبَق للإعلانات" هي ميزة لتحميل الإعلانات تديرها Google في GMA Next-Gen SDK التي تتولّى إدارة تحميل الإعلانات وتخزينها مؤقتًا نيابةً عنك. تتطلّب ميزة "التحميل المُسبَق للإعلانات" تغيير طريقة إدارة تحميل الإعلانات. لتحسين الأداء باستخدام ميزة "التحميل المُسبَق للإعلانات"، عليك إيقاف ميزة التخزين المؤقت المخصّص وتفويض هذه المسؤولية إلى 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)
}
InterstitialAdSnippets.kt

جافا

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

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

عند استخدام ميزة "التحميل المُسبَق للإعلانات"، تحتفظ GMA Next-Gen SDK بالإعلانات المخزّنة مؤقتًا. عندما تريد عرض إعلان، عليك استدعاء طريقة pollAd. 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)
  }
}
InterstitialAdSnippets.kt

جافا

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);
  }
}
InterstitialAdSnippets.java

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

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

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

Kotlin

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

جافا

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

التحقّق من توفّر الإعلانات التي يتم تحميلها مُسبقًا

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

• الحصول على معلومات حول توفّر الإعلانات التي يتم تحميلها مُسبقًا
• الاستماع إلى معلومات حول توفّر الإعلانات التي يتم تحميلها مُسبقًا

الحصول على معلومات حول توفّر الإعلانات التي يتم تحميلها مُسبقًا

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

Kotlin

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

جافا

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

الاستماع إلى معلومات حول توفّر الإعلانات التي يتم تحميلها مُسبقًا

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

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

• لا تستدعِ طريقة 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)
}
InterstitialAdSnippets.kt

جافا

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);
}
InterstitialAdSnippets.java

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

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

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

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

Kotlin

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

جافا

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

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

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

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

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