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

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

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

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

يشرح هذا الدليل كيفية دمج "الإعلانات البينية" في تطبيق Android.

قبل البدء

قبل المتابعة، عليك تنفيذ ما يلي:

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

فهم ميزة "التحميل المسبَق للإعلان" (إصدار تجريبي)

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

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

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

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

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

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

Kotlin

private fun startPreloading(adUnitId: String) {
  // 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)
}

جافا

private void startPreloading(String adUnitId) {
  // 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. لا تخزِّن عنصر الإعلان المحمَّل مسبقًا. عند استدعاء طريقة 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);
}

عندما يصل تطبيقك إلى موضع إعلان ويمكنه طلب الإجراء show، اطلب الإجراء pollAd. لا تستدعِ طريقة pollAd في عمليات الاستدعاء للتحميل المُسبق أو بعد التحقّق من طريقة isAdAvailable لإيقاف عرض إعلان. إذا كنت بحاجة إلى فحص البيانات الوصفية للإعلان قبل عرضه، يمكنك قراءة معلومات الاستجابة بدون إزالة الإعلان من ذاكرة التخزين المؤقت.

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

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

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 الإعلانات مسبقًا تلقائيًا ويعيد محاولة الطلبات التي تعذّر تنفيذها للإعدادات المحمَّلة مسبقًا. لا تستدعِ طلبات التحميل اليدوية في عمليات الاستدعاء التي تعذّر إجراؤها. في طرق رد الاتصال الخاصة بأحداث التحميل المُسبق، لا تستدعِ الطرق pollAd أو destroy أو start. يمكن أن يؤدي استدعاء هذه الطرق في عمليات الاستدعاء إلى استدعاء حلقات تحميل متكررة.

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

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

Kotlin

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

جافا

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

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

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

يوضّح المثال التالي كيفية ضبط حجم المخزن المؤقت:

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}

جافا

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}

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

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

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

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

يجب إبقاء ميزة التحميل المُسبق نشطة أثناء عرض تطبيقك للإعلانات. خلال هذه الفترة، لا تستخدِم طريقة destroy. إذا لم تكن بحاجة إلى عرض إعلانات لرقم تعريف تحميل مسبق معيّن مرة أخرى في الجلسة، يمكنك إيقاف التحميل المسبق للإعلانات. لإيقاف تحميل الإعلانات لرقم تعريف تحميل مسبق معيّن، يمكنك استدعاء الطريقة 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);
}

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

قراءة معلومات استجابة الإعلان التالي الذي تم تحميله مسبقًا بدون إزالة الإعلان من ذاكرة التخزين المؤقت إذا كنت بحاجة إلى فحص البيانات الوصفية للإعلان قبل عرضه، يُرجى قراءة معلومات الاستجابة بدلاً من استدعاء الطريقة pollAd.

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

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