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

اختيار النظام الأساسي: iOS Unity Flutter 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 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 إعلانات تم تحميلها مُسبقًا في الذاكرة. تتم مشاركة هذا الحدّ على مستوى جميع الأشكال ومعرّفات التحميل المُسبَق.
• ننصحك بالاحتفاظ بحجم ذاكرة تخزين مؤقت يبلغ اثنين لكل معرّف تحميل مُسبَق.

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