إعداد الإعلانات البينية

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

الإعلانات البينية هي إعلانات بملء الشاشة تغطي واجهة التطبيق. يتم عرض هذه الإعلانات في نقاط انتقال طبيعية في تطبيقك، مثل بين الأنشطة أو أثناء فترات التوقف المؤقت في مستويات اللعبة.

عندما يعرض تطبيقك إعلانًا بينيًا، يمكن للمستخدمين النقر على الإعلان والمتابعة، أو إغلاق الإعلان والعودة إلى التطبيق. اطّلِع على إحدى دراسات الحالة.

يوضّح هذا الدليل كيفية دمج الإعلانات البينية في تطبيق Android.

قبل البدء

قبل المتابعة، يُرجى اتّباع الخطوات التالية:

  • إعداد GMA Next-Gen SDK
  • استخدِم رقم تعريف الوحدة الإعلانية البينية الاختبارية ca-app-pub-3940256099942544/1033173712.
    • عند إنشاء تطبيقك واختباره، احرص على استخدام إعلانات اختبارية بدلاً من الإعلانات النهائية المباشرة. إذا لم تستخدِم معرّف الوحدة الإعلانية الاختبارية، يمكن أن تعلّق Google حسابك.
    • قبل نشر تطبيقك، استبدِل هذا المعرّف بمعرّف الوحدة الإعلانية.
    • للحصول على تفاصيل حول GMA Next-Gen SDK الإعلانات التجريبية، اطّلِع على مقالة تفعيل الإعلانات التجريبية.

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

تتيح ميزة "التحميل المُسبَق للإعلانات" في GMA Next-Gen SDK تحميل الإعلانات وتخزينها مؤقتًا بشكل آلي.

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

  • إدارة المراجع: تحتفظ بالمراجع إلى أن يتم عرض الإعلانات.
  • إعادة التحميل التلقائي: يتم تحميل إعلان جديد عند استرداد إعلان من ذاكرة التخزين المؤقت.
  • عمليات إعادة المحاولة المُدارة: يتم تحميل إعلان جديد عندما يتعذّر تحميل إعلان آخر.
  • التعامل مع انتهاء الصلاحية: إعادة تحميل الإعلانات قبل انتهاء صلاحيتها
  • تحسين ذاكرة التخزين المؤقت: تعمل هذه الميزة على تحسين ترتيب ذاكرة التخزين المؤقت لعرض الإعلان ذي الأولوية الأعلى.

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

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

يوضّح المثال التالي كيفية بدء التحميل المُسبَق للإعلانات:

Kotlin

// Call start() once after SDK initialization.
// Preload only one ad unit per format to optimize performance.
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
InterstitialAdPreloader.start(adUnitId, preloadConfig)

جافا

// Call start() once after SDK initialization.
// Preload only one ad unit per format to optimize performance.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
InterstitialAdPreloader.start(adUnitId, preloadConfig);

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

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

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

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

عند توفّر عنصر إعلان، استدعِ الطريقة show لعرض الإعلان. يوضّح المثال التالي كيفية استرداد إعلان تم تحميله مسبقًا وعرضه:

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)
  if (ad == null) {
    Log.e(TAG, "Interstitial ad is not available.")
    return
  }

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

جافا

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.e(TAG, "Interstitial ad is not available.");
    return;
  }

  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.");
        }
      });

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

تجنَّب طلب طريقة pollAd() إلى أن تصبح مستعدًا لعرض إعلان. للاطّلاع على معلومات استجابة الإعلان بدون عرضها، يُرجى الاطّلاع على قراءة معلومات الردّ.

الاستماع إلى أحداث الإعلانات

قبل عرض الإعلان، استمِع إلى أحداث الإعلان. يوضّح المثال التالي كيفية تسجيل دوال ردّ الاتصال لأحداث الإعلانات:

Kotlin

// Listen for ad events.
val ad = interstitialAd
if (ad == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.")
  return
}

ad.adEventCallback =
  object : InterstitialAdEventCallback {
    override fun onAdShowedFullScreenContent() {
      // Interstitial ad did show.
    }

    override fun onAdDismissedFullScreenContent() {
      // Interstitial ad did dismiss.
      interstitialAd = null
    }

    override fun onAdFailedToShowFullScreenContent(
      fullScreenContentError: FullScreenContentError
    ) {
      // Interstitial ad failed to show.
      Log.e(TAG, "Interstitial ad failed to show: ${fullScreenContentError.message}")
    }

    override fun onAdImpression() {
      // Interstitial ad did record an impression.
    }

    override fun onAdClicked() {
      // Interstitial ad did record a click.
    }
  }

جافا

// Listen for ad events.
if (interstitialAd == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.");
  return;
}

interstitialAd.setAdEventCallback(
    new InterstitialAdEventCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Interstitial ad did show.
      }

      @Override
      public void onAdDismissedFullScreenContent() {
        // Interstitial ad did dismiss.
        interstitialAd = null;
      }

      @Override
      public void onAdFailedToShowFullScreenContent(
          @NonNull FullScreenContentError fullScreenContentError) {
        // Interstitial ad failed to show.
        Log.e(TAG, "Interstitial ad failed to show: " + fullScreenContentError.getMessage());
      }

      @Override
      public void onAdImpression() {
        // Interstitial ad did record an impression.
      }

      @Override
      public void onAdClicked() {
        // Interstitial ad did record a click.
      }
    });

اختياري: الاستماع إلى أحداث التحميل المُسبَق

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

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

Kotlin

val preloadCallback =
  // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(
        TAG,
        ("Interstitial preload ad $preloadId failed to load with error: ${adError.message}"),
      )
    }

    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)

جافا

PreloadCallback preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            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(@NonNull 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(@NonNull String preloadId, @NonNull 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);

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

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

إذا كنت بحاجة إلى معرفة ما إذا كان الإعلان متاحًا، تحقّق من توفّره. يوضّح المثال التالي كيفية التحقّق مما إذا كان الإعلان المحمَّل مسبقًا متاحًا:

Kotlin

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

جافا

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

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

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

يوضّح المثال التالي كيفية ضبط حجم ذاكرة التخزين المؤقت على أربعة إعلانات محملة مسبقًا:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Maintain small or default buffer size unless rapid transitions are expected.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
InterstitialAdPreloader.start(adUnitId, preloadConfig)

جافا

// Maintain small or default buffer size unless rapid transitions are expected.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
InterstitialAdPreloader.start(adUnitId, preloadConfig);

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

تفرض GMA Next-Gen SDK حدًا على مستوى التطبيق على إجمالي عدد الإعلانات المحمَّلة مسبقًا في جميع الوحدات الإعلانية ومعرّفات التحميل المُسبَق:

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

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

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

يوضّح المثال التالي كيفية إيقاف التحميل المُسبَق للإعلانات:

Kotlin

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  InterstitialAdPreloader.destroy(adUnitId)
}

جافا

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  InterstitialAdPreloader.destroy(adUnitId);
}

اختياري: قراءة معلومات الرد

قراءة معلومات استجابة الإعلان التالي الذي تم تحميله مسبقًا بدون إزالة الإعلان من ذاكرة التخزين المؤقت

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

Kotlin

val responseInfo = InterstitialAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

جافا

ResponseInfo responseInfo = InterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());