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

ميزة "التحميل المُسبَق للإعلانات" هي ميزة لتحميل الإعلانات تديرها Google في Google Mobile Ads SDK (Legacy)، وتتولّى إدارة تحميل الإعلانات وتخزينها مؤقتًا بالنيابة عنك. يتطلّب التحميل المسبَق للإعلان إجراء تغيير في طريقة إدارة تحميل الإعلانات. لتحسين الأداء باستخدام ميزة التحميل المُسبَق للإعلانات، عليك إيقاف التخزين المؤقت المخصّص وتفويض هذه المسؤولية إلى Google Mobile Ads SDK (Legacy).

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

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

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

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

قبل المتابعة في هذا البرنامج التعليمي، عليك إعداد Google Mobile Ads SDK (Legacy).

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

عند بدء تشغيل التطبيق، استدعِ الطريقة start مرة واحدة. بعد استدعاء الطريقة start، Google Mobile Ads SDK (Legacy) يتم تلقائيًا تحميل الإعلانات مسبقًا وإعادة محاولة الطلبات غير الناجحة للإعدادات المحمَّلة مسبقًا.

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

// Define a PreloadConfiguration.
val configuration = PreloadConfiguration.Builder("AD_UNIT_ID").build()
// Start the preloading with a given preload ID, preload configuration.
InterstitialAdPreloader.start("AD_UNIT_ID", configuration)
InterstitialAdPreloaderSnippets.kt

// Define a PreloadConfiguration.
PreloadConfiguration configuration = new PreloadConfiguration.Builder("AD_UNIT_ID").build();
// Start the preloading with a given preload ID, preload configuration.
InterstitialAdPreloader.start("AD_UNIT_ID", configuration);
InterstitialAdPreloaderSnippets.java

استبدِل AD_UNIT_ID برقم تعريف الوحدة الإعلانية.

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

عند استخدام ميزة "التحميل المُسبَق للإعلانات"، يحتفظ Google Mobile Ads SDK (Legacy) بالإعلانات المخزّنة مؤقتًا. عندما تريد عرض إعلان، استدعِ الطريقة pollAd. يستردّ Google Mobile Ads SDK (Legacy) إعلانًا متاحًا ويحمّل تلقائيًا الإعلان التالي مسبقًا في الخلفية.

تجنَّب استدعاء طريقة pollAd إلى أن تصبح مستعدًا لعرض إعلان. يسمح الاحتفاظ بالإعلانات في ذاكرة التخزين المؤقت Google Mobile Ads SDK (Legacy) بالتحديث التلقائي للإعلانات المنتهية الصلاحية وتحسين ذاكرة التخزين المؤقت.

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

// pollAd() returns the next available ad and loads another ad in the background.
val ad = InterstitialAdPreloader.pollAd("AD_UNIT_ID")

// [Optional] Interact with the ad as needed.
ad?.onPaidEventListener = OnPaidEventListener {
  // [Optional] Send the impression-level ad revenue information to your preferred
  // analytics server directly within this callback.
}

// Show the ad immediately.
ad?.show(activity)
InterstitialAdPreloaderSnippets.kt

// pollAd() returns the next available ad and loads another ad in the background.
InterstitialAd ad = InterstitialAdPreloader.pollAd("AD_UNIT_ID");

if (ad != null) {
  // [Optional] Interact with the ad object as needed.
  ad.setOnPaidEventListener(
      adValue -> {
        // [Optional] Send the impression-level ad revenue information to your preferred
        // analytics server directly within this callback.
      });

  // Show the ad immediately.
  ad.show(activity);
}
InterstitialAdPreloaderSnippets.java

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

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

• الحصول على معلومات حول توفّر الإعلانات المحمَّلة مسبقًا
• الاستماع إلى مدى توفّر الإعلانات المحمَّلة مسبقًا

الحصول على معلومات حول توفّر الإعلانات المحمَّلة مسبقًا

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

// Verify that a preloaded ad is available.
if (!InterstitialAdPreloader.isAdAvailable("AD_UNIT_ID")) {
  // No ads are available to show.
}
InterstitialAdPreloaderSnippets.kt

// Verify that a preloaded ad is available.
if (!InterstitialAdPreloader.isAdAvailable("AD_UNIT_ID")) {
  // No ads are available to show.
}
InterstitialAdPreloaderSnippets.java

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

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

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

• لا تتّصل بالرقم ‎start.
• تجنَّب طلب pollAd ما لم يكن سيتم عرض الإعلان على الفور.

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

// Define a callback to receive preload events.
val callback =
  object : PreloadCallbackV2() {
    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo?) {
      // Called when preloaded ads are available.
    }

    override fun onAdsExhausted(preloadId: String) {
      // Called when no preloaded ads are available.
    }

    override fun onAdFailedToPreload(preloadId: String, adError: AdError) {
      // Called when preloaded ads failed to load.
    }
  }
InterstitialAdPreloaderSnippets.kt

// Define a callback to receive preload events.
PreloadCallbackV2 callback =
    new PreloadCallbackV2() {
      @Override
      public void onAdPreloaded(
          @NonNull String preloadId, @Nullable ResponseInfo responseInfo) {
        // Called when preloaded ads are available.
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        // Called when no preloaded ads are available.
      }

      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull AdError adError) {
        // Called when preloaded ads failed to load.
      }
    };
InterstitialAdPreloaderSnippets.java

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

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

// Stops the preloading and destroy preloaded ads.
InterstitialAdPreloader.destroy("AD_UNIT_ID")
// Stops the preloading and destroy all ads.
InterstitialAdPreloader.destroyAll()
InterstitialAdPreloaderSnippets.kt

// Stops the preloading and destroy preloaded ads.
InterstitialAdPreloader.destroy("AD_UNIT_ID");
// Stops the preloading and destroy all ads.
InterstitialAdPreloader.destroyAll();
InterstitialAdPreloaderSnippets.java

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

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

// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val configuration = PreloadConfiguration.Builder("AD_UNIT_ID").setBufferSize(2).build()
InterstitialAdPreloaderSnippets.kt

// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
PreloadConfiguration configuration =
    new PreloadConfiguration.Builder("AD_UNIT_ID").setBufferSize(2).build();
InterstitialAdPreloaderSnippets.java

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

تفرض Google Mobile Ads SDK (Legacy) حدًا على مستوى التطبيق على إجمالي عدد الإعلانات المحمَّلة مسبقًا في جميع الوحدات الإعلانية ومعرّفات التحميل المُسبَق:

• الحدّ التلقائي: Google Mobile Ads SDK (Legacy)، ويحتوي على 6 إعلانات محملة مسبقًا كحدّ أقصى في الذاكرة. ويتم تطبيق هذا الحد على جميع التنسيقات وأرقام تعريف التحميل المُسبَق.
• ننصحك بإبقاء حجم ذاكرة التخزين المؤقت على اثنين لكل معرّف تحميل مُسبَق.