إعداد "الإعلانات على شاشة فتح التطبيق"

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

"الإعلانات على شاشة فتح التطبيق" هي شكل إعلان مخصّص للناشرين الذين يريدون تحقيق الربح من شاشات تحميل تطبيقاتهم. يمكن للمستخدِمين إغلاق "الإعلانات على شاشة فتح التطبيق" في أي وقت. عندما يعود المستخدِمون إلى تطبيقك، اعرِض لهم "الإعلانات على شاشة فتح التطبيق".

لمزيد من المعلومات، اطّلِع على إرشادات "الإعلانات على شاشة فتح التطبيق".

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

قبل البدء

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

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

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

تعمل ميزة التحميل المُسبَق للإعلانات (إصدار تجريبي) في GMA Next-Gen SDK على أتمتة تحميل الإعلانات وتخزينها مؤقتًا.

تقدّم ميزة التحميل المُسبَق للإعلانات المزايا التالية:

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

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

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

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

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
AppOpenAdPreloader.start(adUnitId, preloadConfig)

جافا

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
AppOpenAdPreloader.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 = AppOpenAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "App open ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "App open ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : AppOpenAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "App open 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.
  AppOpenAd ad = AppOpenAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "App open ad is not available.");
    return;
  }

  Log.d(TAG, "App open ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new AppOpenAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "App open ad recorded an impression.");
        }
      });

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

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

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

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

Kotlin

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = appOpenAd
  if (ad == null) {
    Log.e(TAG, "App open ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : AppOpenAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // App open ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // App open ad did dismiss.
        appOpenAd = null
      }

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

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

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

جافا

private void listenToAdEvents() {
  // Listen for ad events.
  if (appOpenAd == null) {
    Log.e(TAG, "App open ad is not ready yet.");
    return;
  }

  appOpenAd.setAdEventCallback(
      new AppOpenAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // App open ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // App open ad did dismiss.
          appOpenAd = null;
        }

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

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

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

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

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

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

Kotlin

val preloadCallback =
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(TAG, "App open preload ad $preloadId failed to load with error: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "App open preload ad $preloadId is not available")
    }

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

جافا

PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "App open preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        Log.i(TAG, String.format("App open preload ad %s is not available", preloadId));
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, String.format("App open preload ad %s is available", preloadId));
      }
    };
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
AppOpenAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

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

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

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

Kotlin

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

جافا

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

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

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

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

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
AppOpenAdPreloader.start(adUnitId, preloadConfig)

جافا

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);
AppOpenAdPreloader.start(adUnitId, preloadConfig);

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

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

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

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

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

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

Kotlin

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

جافا

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

اختياري: قراءة معلومات الاستجابة

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

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

Kotlin

val responseInfo = AppOpenAdPreloader.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 = AppOpenAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

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

التعامل مع عمليات بدء التشغيل على البارد وشاشات التحميل

تحدث عملية بدء التشغيل على البارد عندما يتم تشغيل تطبيقك من القرص، بينما تحدث عملية إعادة التشغيل البطيء عندما تعيد فتح التطبيق من الذاكرة. أثناء عملية بدء التشغيل على البارد، لا يتوفّر لديك إعلان مُحمَّل مُسبقًا لعرضه على الفور. أثناء إعادة التشغيل البطيء، قد يظل لديك إعلان مُحمَّل مُسبقًا وجاهز للعرض.

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

الاقتراحات

اتّبِع هذه الاقتراحات بشأن "الإعلانات على شاشة فتح التطبيق":

  • لا تعرِض "إعلانًا على شاشة فتح التطبيق" عند بدء تشغيل التطبيق لأول مرة.
  • إذا اكتمل تحميل شاشة التحميل أثناء عرض الإعلان، أغلِق شاشة التحميل في طريقة معاودة الاتصال `adDismissed`.
  • تنتهي صلاحية "الإعلانات على شاشة فتح التطبيق" بعد أربع ساعات من تحميلها. لا تعرِض "إعلانًا على شاشة فتح التطبيق" تم تحميله منذ أكثر من أربع ساعات.