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

التحميل المسبَق للإعلان هو ميزة تحميل إعلانات تديرها 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) تلقائيًا على تحميل الإعلانات مسبقًا وإعادة محاولة الطلبات التي تعذّر تنفيذها للإعدادات التي تم تحميلها مسبقًا.

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

Kotlin

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

جافا

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

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

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

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

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

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

Kotlin

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

جافا

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

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

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

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

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

Kotlin

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

جافا

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

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

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

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

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

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

Kotlin

// 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.
    }
  }

جافا

// 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.
      }
    };

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

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

Kotlin

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

جافا

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

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

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

Kotlin

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

جافا

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

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

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

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