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

اختيار النظام الأساسي: 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 لكل معرّف تحميل مُسبَق.

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