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

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

ميزة "التحميل المُسبَق للإعلانات" هي ميزة تديرها 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)
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) بتحديث الإعلانات منتهية الصلاحية تلقائيًا وتنفيذ عملية تحسين ذاكرة التخزين المؤقت.

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

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

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

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

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

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

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

Kotlin

// 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 إلا إذا كان سيتم عرض الإعلان على الفور.

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

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

Kotlin

// 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 تلقائيًا حجم ذاكرة التخزين المؤقت لتحقيق التوازن بين استهلاك الذاكرة والمدة المستغرَقة لعرض الإعلانات. إذا كان تطبيقك يعرض الإعلانات قبل تحميل الإعلان التالي، يمكنك ضبط حجم ذاكرة تخزين مؤقت مخصّص لزيادة عدد الإعلانات المحفوظة في الذاكرة.

Kotlin

// Define a PreloadConfiguration and buffer up to 3 preloaded ads.
val configuration = PreloadConfiguration.Builder("AD_UNIT_ID").setBufferSize(3).build()
InterstitialAdPreloaderSnippets.kt

جافا

// Define a PreloadConfiguration and buffer up to 3 preloaded ads.
PreloadConfiguration configuration =
    new PreloadConfiguration.Builder("AD_UNIT_ID").setBufferSize(3).build();
InterstitialAdPreloaderSnippets.java

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

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

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

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