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

حزمة تطوير البرامج (SDK)

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

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

قبل البدء

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

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

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

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

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

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

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

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

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

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

private void startPreloading(String adUnitId) {
  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 لعرض الإعلان. يوضّح المثال التالي كيفية استرداد إعلان تم تحميله مسبقًا وعرضه:

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

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

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

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

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

private void startPreloadingWithCallback(String adUnitId) {
  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 حجم ذاكرة التخزين المؤقت تلقائيًا لتحقيق التوازن بين استهلاك الذاكرة والمدة المستغرقة لعرض الإعلانات. يمكنك ضبط حجم ذاكرة التخزين المؤقت المخصّص لزيادة عدد الإعلانات المخزّنة في الذاكرة. ننصحك بضبط حجم ذاكرة التخزين المؤقت على أربعة إعلانات كحد أقصى.

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

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Four is the recommended maximum buffer size.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 4)
  AppOpenAdPreloader.start(adUnitId, preloadConfig)
}

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  // Four is the recommended maximum buffer size.
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 4);
  AppOpenAdPreloader.start(adUnitId, preloadConfig);
}

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

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

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

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

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

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

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

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

عليك تحميل مواد عرض التطبيق على سلسلة محادثات في الخلفية حتى يستمر التحميل أثناء عرض الإعلان.

أفضل الممارسات

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

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