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

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

تحذير: لا يمكن لبعض المستخدِمين استخدام هذه الميزة. لطلب إذن الوصول، يُرجى التواصل مع مدير حسابك.

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

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

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

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

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

قبل المتابعة في هذا البرنامج التعليمي، عليك إكمال ما يلي:

• ثبِّت الإصدار 0.14.0-alpha01 أو إصدارًا أحدث من GMA Next-Gen SDK.
• إعداد GMA Next-Gen SDK

• اختياري: نزِّل التطبيق النموذجي وشغِّله.

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

لبدء التحميل المُسبَق للإعلانات، يُرجى الاتصال بالرقم startPreload(). يجب استدعاء هذه الطريقة مرة واحدة فقط في بداية التطبيق. بعد استدعاء startPreload()، يتم تلقائيًا التحميل المُسبَق للإعلانات وإعادة محاولة الطلبات غير الناجحة للإعدادات المحمَّلة مُسبقًا.GMA Next-Gen SDK

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

Kotlin

private fun startPreloading(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}
InterstitialAdSnippets.kt

جافا

private void startPreloading(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}
InterstitialAdSnippets.java

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

عند استخدام ميزة "التحميل المُسبَق للإعلانات"، يحتفظ GMA Next-Gen SDK بالإعلانات المخزّنة مؤقتًا. عندما تريد عرض إعلان، استدعِ الدالة pollAd(). يستردّ GMA Next-Gen SDK الإعلان المتاح ويحمّل تلقائيًا الإعلان التالي مسبقًا في الخلفية.

تجنَّب استدعاء هذه الطريقة إلى أن تصبح مستعدًا لعرض إعلان. يسمح الاحتفاظ بالإعلانات في ذاكرة التخزين المؤقت لـ GMA Next-Gen SDK بإعادة تحميل الإعلانات المنتهية الصلاحية تلقائيًا وتحسين ذاكرة التخزين المؤقت.

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

Kotlin

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = InterstitialAdPreloader.pollAd(adUnitId)

  // Interact with the ad object as needed.
  ad?.apply {
    Log.d(TAG, "Interstitial ad response info: ${this.getResponseInfo()}")
    this.adEventCallback =
      object : InterstitialAdEventCallback {
        override fun onAdImpression() {
          Log.d(TAG, "Interstitial ad recorded an impression.")
        }

        override fun onAdPaid(value: AdValue) {
          Log.d(TAG, "Interstitial ad onPaidEvent: ${value.valueMicros} ${value.currencyCode}")
        }
      }

    // Show the ad.
    ad.show(activity)
  }
}
InterstitialAdSnippets.kt

جافا

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  final InterstitialAd ad = InterstitialAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad != null) {
    Log.d(TAG, "Interstitial ad response info: " + ad.getResponseInfo());
    ad.setAdEventCallback(
        new InterstitialAdEventCallback() {
          @Override
          public void onAdImpression() {
            Log.d(TAG, "Interstitial ad recorded an impression.");
          }

          @Override
          public void onAdPaid(AdValue value) {
            Log.d(
                TAG,
                "Interstitial ad onPaidEvent: "
                    + value.getValueMicros()
                    + " "
                    + value.getCurrencyCode());
          }
        });

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

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

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

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

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

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

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return InterstitialAdPreloader.isAdAvailable(adUnitId)
}
InterstitialAdSnippets.kt

جافا

private boolean isAdAvailable(String adUnitId) {
  return InterstitialAdPreloader.isAdAvailable(adUnitId);
}
InterstitialAdSnippets.java

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

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

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

• لا تتّصل بالرقم startPreload().
• تجنَّب استدعاء pollAd() ما لم يكن سيتم عرض الإعلان على الفور.

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

Kotlin

private fun startPreloadingWithCallback(adUnitId: String) {
  val preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    object : PreloadCallback {
      override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
        Log.i(
          TAG,
          ("Interstitial preload ad $preloadId failed to load with error: ${adError.message}"),
        )
        // [Optional] Get the error response info for additional details.
        // val responseInfo = adError.responseInfo
      }

      override fun onAdsExhausted(preloadId: String) {
        Log.i(TAG, "Interstitial preload ad $preloadId is not available")
        // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
      }

      override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
        Log.i(TAG, "Interstitial preload ad $preloadId is available")
      }
    }
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)
}
InterstitialAdSnippets.kt

جافا

private void startPreloadingWithCallback(String adUnitId) {
  PreloadCallback preloadCallback =
      // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
      new PreloadCallback() {
        @Override
        public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
          Log.e(
              TAG,
              String.format(
                  "Interstitial preload ad %s failed to load with error: %s",
                  preloadId, adError.getMessage()));
          // [Optional] Get the error response info for additional details.
          // ResponseInfo responseInfo = adError.getResponseInfo();
        }

        @Override
        public void onAdsExhausted(String preloadId) {
          Log.i(TAG, "Interstitial preload ad " + preloadId + " is not available");
          // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
        }

        @Override
        public void onAdPreloaded(String preloadId, ResponseInfo responseInfo) {
          Log.i(TAG, "Interstitial preload ad " + preloadId + " is available");
        }
      };

  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);
}
InterstitialAdSnippets.java

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

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

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

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

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 3)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}
InterstitialAdSnippets.kt

جافا

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 3);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}
InterstitialAdSnippets.java