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

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

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

قبل البدء

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

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

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

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

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

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

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

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

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

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 أي إعلانات.

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. لقراءة معلومات استجابة الإعلان بدون عرضها، يُرجى الاطّلاع على قراءة معلومات الردّ.

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

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

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

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

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

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

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 تلقائيًا على التحميل المُسبَق للإعلانات وإعادة محاولة الطلبات التي تعذّر تنفيذها لعمليات الإعداد المحمَّلة مُسبقًا.

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

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

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

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

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

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

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

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 إلى إزالة جميع الإعلانات المحمَّلة مسبقًا والمرتبطة بمعرّف التحميل المُسبَق من ذاكرة التخزين المؤقت.

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

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

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

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

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

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

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

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

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

الاقتراحات

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

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