حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" في وضع الصيانة للحصول على آخر التحديثات والميزات، عليك migrate وإعداد "الجيل التالي من SDK لإعلانات Google على الأجهزة الجوّالة".

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

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

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

هذا الدليل مخصّص للناشرين الذين يدمجون "الإعلانات على شاشة فتح التطبيق" باستخدام Google Mobile Ads SDK (Legacy).

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

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

المتطلبات الأساسية

اختبِر دائمًا باستخدام الإعلانات الاختبارية

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

أسهل طريقة لتحميل الإعلانات الاختبارية هي استخدام معرّف الوحدة الإعلانية الاختبارية المخصّص لـ "الإعلانات على شاشة فتح التطبيق":

ca-app-pub-3940256099942544/9257395921

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

لمزيد من المعلومات حول طريقة عمل الإعلانات الاختبارية في Google Mobile Ads SDK (Legacy)، يُرجى الاطّلاع على مقالة تفعيل الإعلانات الاختبارية.

توسيع فئة Application

أنشِئ فئة جديدة تمدّد الفئة Application. يوفّر ذلك طريقة تراعي مراحل النشاط لإدارة الإعلانات المرتبطة بحالة التطبيق بدلاً من Activity واحد:

جافا

public class MyApplication extends Application
    implements ActivityLifecycleCallbacks, DefaultLifecycleObserver {

  private AppOpenAdManager appOpenAdManager;
  private Activity currentActivity;

  @Override
  public void onCreate() {
    super.onCreate();
    this.registerActivityLifecycleCallbacks(this);

    ProcessLifecycleOwner.get().getLifecycle().addObserver(this);
    appOpenAdManager = new AppOpenAdManager();
  }
MyApplication.java

Kotlin

class MyApplication :
  Application(), Application.ActivityLifecycleCallbacks, DefaultLifecycleObserver {

  private lateinit var appOpenAdManager: AppOpenAdManager
  private var currentActivity: Activity? = null

  override fun onCreate() {
    super<Application>.onCreate()
    registerActivityLifecycleCallbacks(this)

    ProcessLifecycleOwner.get().lifecycle.addObserver(this)
    appOpenAdManager = AppOpenAdManager()
  }
MyApplication.kt

بعد ذلك، أضِف الرمز التالي إلى AndroidManifest.xml:

<!-- TODO: Update to reference your actual package name. -->
<application
    android:name="com.google.android.gms.example.appopendemo.MyApplication" ...>
...
</application>

تنفيذ مكوّن الأداة المساعدة

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

نفِّذ مكوّنًا مساعدًا AppOpenAdManager لتضمين العمل المرتبط بتحميل "الإعلانات على شاشة فتح التطبيق" وعرضها:

جافا

private class AppOpenAdManager {

  private static final String LOG_TAG = "AppOpenAdManager";
  private static final String AD_UNIT_ID = "ca-app-pub-3940256099942544/9257395921";

  private AppOpenAd appOpenAd = null;
  private boolean isLoadingAd = false;
  private boolean isShowingAd = false;

  /** Keep track of the time an app open ad is loaded to ensure you don't show an expired ad. */
  private long loadTime = 0;

  /** Constructor. */
  public AppOpenAdManager() {}MyApplication.java

Kotlin

private inner class AppOpenAdManager {

  private var appOpenAd: AppOpenAd? = null
  private var isLoadingAd = false
  var isShowingAd = false

  /** Keep track of the time an app open ad is loaded to ensure you don't show an expired ad. */
  private var loadTime: Long = 0MyApplication.kt

لاستخدام AppOpenAdManager، يمكنك استدعاء طرق برنامج تضمين البيانات العامة في مثيل MyApplication الفردي. تتفاعل فئة Application مع بقية الرمز، وتفوّض عمل تحميل الإعلان وعرضه إلى المدير.

تحميل إعلان

الخطوة التالية هي ملء طريقة loadAd ومعالجة عمليات الاستدعاء لتحميل الإعلان.

جافا

AppOpenAd.load(
    context,
    "AD_UNIT_ID",
    new AdRequest.Builder().build(),
    new AppOpenAdLoadCallback() {
      @Override
      public void onAdLoaded(AppOpenAd ad) {
        // Called when an app open ad has loaded.
        Log.d(LOG_TAG, "App open ad loaded.");

        appOpenAd = ad;
        isLoadingAd = false;
        loadTime = (new Date()).getTime();
      }

      @Override
      public void onAdFailedToLoad(LoadAdError loadAdError) {
        // Called when an app open ad has failed to load.
        Log.d(LOG_TAG, "App open ad failed to load with error: " + loadAdError.getMessage());

        isLoadingAd = false;
      }
    });MyApplication.java

Kotlin

AppOpenAd.load(
  context,
  "AD_UNIT_ID",
  AdRequest.Builder().build(),
  object : AppOpenAdLoadCallback() {
    override fun onAdLoaded(ad: AppOpenAd) {
      // Called when an app open ad has loaded.
      Log.d(LOG_TAG, "App open ad loaded.")

      appOpenAd = ad
      isLoadingAd = false
      loadTime = Date().time
    }

    override fun onAdFailedToLoad(loadAdError: LoadAdError) {
      // Called when an app open ad has failed to load.
      Log.d(LOG_TAG, "App open ad failed to load with error: " + loadAdError.message)

      isLoadingAd = false
    }
  },
)MyApplication.kt

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

عرض الإعلان

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

يعرض الرمز التالي إعلانًا ثم يعيد تحميله:

جافا

public void showAdIfAvailable(
    @NonNull final Activity activity,
    @NonNull OnShowAdCompleteListener onShowAdCompleteListener) {
  // If the app open ad is already showing, do not show the ad again.
  if (isShowingAd) {
    Log.d(TAG, "The app open ad is already showing.");
    return;
  }

  // If the app open ad is not available yet, invoke the callback then load the ad.
  if (appOpenAd == null) {
    Log.d(TAG, "The app open ad is not ready yet.");
    onShowAdCompleteListener.onShowAdComplete();
    // Load an ad.
    return;
  }

  isShowingAd = true;
  appOpenAd.show(activity);
}
AppOpenAdSnippets.java

Kotlin

fun showAdIfAvailable(activity: Activity, onShowAdCompleteListener: OnShowAdCompleteListener) {
  // If the app open ad is already showing, do not show the ad again.
  if (isShowingAd) {
    Log.d(TAG, "The app open ad is already showing.")
    return
  }

  // If the app open ad is not available yet, invoke the callback then load the ad.
  if (appOpenAd == null) {
    Log.d(TAG, "The app open ad is not ready yet.")
    onShowAdCompleteListener.onShowAdComplete()
    // Load an ad.
    return
  }

  isShowingAd = true
  appOpenAd?.show(activity)
}
AppOpenAdSnippets.kt

ضبط FullScreenContentCallback

يعالج FullScreenContentCallback الأحداث المتعلقة بعرض AppOpenAd. قبل عرض "AppOpenAd"، تأكَّد من ضبط دالة الاستدعاء:

جافا

appOpenAd.setFullScreenContentCallback(
    new FullScreenContentCallback() {
      @Override
      public void onAdDismissedFullScreenContent() {
        // Called when full screen content is dismissed.
        Log.d(TAG, "Ad dismissed fullscreen content.");
        // Don't forget to set the ad reference to null so you
        // don't show the ad a second time.
        appOpenAd = null;
        isShowingAd = false;

        onShowAdCompleteListener.onShowAdComplete();
        // Load an ad.
      }

      @Override
      public void onAdFailedToShowFullScreenContent(@NonNull AdError adError) {
        // Called when full screen content failed to show.
        Log.d(TAG, adError.getMessage());
        appOpenAd = null;
        // Don't forget to set the ad reference to null so you
        // don't show the ad a second time.
        isShowingAd = false;

        onShowAdCompleteListener.onShowAdComplete();
        // Load an ad.
      }

      @Override
      public void onAdShowedFullScreenContent() {
        Log.d(TAG, "Ad showed fullscreen content.");
      }

      @Override
      public void onAdImpression() {
        // Called when an impression is recorded for an ad.
        Log.d(TAG, "The ad recorded an impression.");
      }

      @Override
      public void onAdClicked() {
        // Called when ad is clicked.
        Log.d(TAG, "The ad was clicked.");
      }
    });AppOpenAdSnippets.java

Kotlin

appOpenAd?.fullScreenContentCallback =
  object : FullScreenContentCallback() {
    override fun onAdDismissedFullScreenContent() {
      // Called when full screen content is dismissed.
      Log.d(TAG, "Ad dismissed fullscreen content.")
      // Don't forget to set the ad reference to null so you
      // don't show the ad a second time.
      appOpenAd = null
      isShowingAd = false

      onShowAdCompleteListener.onShowAdComplete()
      // Load an ad.
    }

    override fun onAdFailedToShowFullScreenContent(adError: AdError) {
      // Called when full screen content failed to show.
      Log.d(TAG, adError.message)
      // Don't forget to set the ad reference to null so you
      // don't show the ad a second time.
      appOpenAd = null
      isShowingAd = false

      onShowAdCompleteListener.onShowAdComplete()
      // Load an ad.
    }

    override fun onAdShowedFullScreenContent() {
      Log.d(TAG, "Ad showed fullscreen content.")
    }

    override fun onAdImpression() {
      // Called when an impression is recorded for an ad.
      Log.d(TAG, "The ad recorded an impression.")
    }

    override fun onAdClicked() {
      // Called when ad is clicked.
      Log.d(TAG, "The ad was clicked.")
    }
  }AppOpenAdSnippets.kt

مراعاة انتهاء صلاحية الإعلانات

للتأكّد من عدم عرض إعلان منتهي الصلاحية، أضِف طريقة إلى AppOpenAdManager تتحقّق من المدة التي انقضت منذ تحميل مرجع الإعلان. بعد ذلك، استخدِم هذه الطريقة للتحقّق مما إذا كان الإعلان لا يزال صالحًا.

جافا

/** Check if ad was loaded more than n hours ago. */
private boolean wasLoadTimeLessThanNHoursAgo(long numHours) {
  long dateDifference = (new Date()).getTime() - loadTime;
  long numMilliSecondsPerHour = 3600000;
  return (dateDifference < (numMilliSecondsPerHour * numHours));
}

/** Check if ad exists and can be shown. */
private boolean isAdAvailable() {
  // For time interval details, see: https://support.google.com/admob/answer/9341964
  return appOpenAd != null && wasLoadTimeLessThanNHoursAgo(4);
}
MyApplication.java

Kotlin

/** Check if ad was loaded more than n hours ago. */
private fun wasLoadTimeLessThanNHoursAgo(numHours: Long): Boolean {
  val dateDifference: Long = Date().time - loadTime
  val numMilliSecondsPerHour: Long = 3600000
  return dateDifference < numMilliSecondsPerHour * numHours
}

/** Check if ad exists and can be shown. */
private fun isAdAvailable(): Boolean {
  // For time interval details, see: https://support.google.com/admob/answer/9341964
  return appOpenAd != null && wasLoadTimeLessThanNHoursAgo(4)
}
MyApplication.kt

تتبُّع النشاط الحالي

لعرض الإعلان، يجب أن يكون سياق Activity متوفّرًا. لتتبُّع أحدث نشاط يتم استخدامه، يمكنك التسجيل في Application.ActivityLifecycleCallbacks وتنفيذها.

جافا

@Override
public void onActivityCreated(@NonNull Activity activity, @Nullable Bundle savedInstanceState) {}

@Override
public void onActivityStarted(@NonNull Activity activity) {
  // An ad activity is started when an ad is showing, which could be AdActivity class from Google
  // SDK or another activity class implemented by a third party mediation partner. Updating the
  // currentActivity only when an ad is not showing will ensure it is not an ad activity, but the
  // one that shows the ad.
  if (!appOpenAdManager.isShowingAd) {
    currentActivity = activity;
  }
}

@Override
public void onActivityResumed(@NonNull Activity activity) {}

@Override
public void onActivityPaused(@NonNull Activity activity) {}

@Override
public void onActivityStopped(@NonNull Activity activity) {}

@Override
public void onActivitySaveInstanceState(@NonNull Activity activity, @NonNull Bundle outState) {}

@Override
public void onActivityDestroyed(@NonNull Activity activity) {}
MyApplication.java

Kotlin

override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {}

override fun onActivityStarted(activity: Activity) {
  // An ad activity is started when an ad is showing, which could be AdActivity class from Google
  // SDK or another activity class implemented by a third party mediation partner. Updating the
  // currentActivity only when an ad is not showing will ensure it is not an ad activity, but the
  // one that shows the ad.
  if (!appOpenAdManager.isShowingAd) {
    currentActivity = activity
  }
}

override fun onActivityResumed(activity: Activity) {}

override fun onActivityPaused(activity: Activity) {}

override fun onActivityStopped(activity: Activity) {}

override fun onActivitySaveInstanceState(activity: Activity, outState: Bundle) {}

override fun onActivityDestroyed(activity: Activity) {}
MyApplication.kt

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

الاستماع إلى أحداث فتح التطبيق

للاستماع إلى أحداث فتح التطبيق، اتّبِع الخطوات التالية:

إضافة المكتبات إلى ملف gradle

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

Kotlin

  dependencies {
    implementation("com.google.android.gms:play-services-ads:25.5.0")
    implementation("androidx.lifecycle:lifecycle-process:2.8.3")
  }

Groovy

  dependencies {
    implementation 'com.google.android.gms:play-services-ads:25.5.0'
    implementation 'androidx.lifecycle:lifecycle-process:2.8.3'
  }

تنفيذ واجهة مراقبة مراحل النشاط

يمكنك الاستماع إلى أحداث فتح التطبيق من خلال تنفيذ واجهة DefaultLifecycleObserver.

نفِّذ onStart() لعرض "الإعلان على شاشة فتح التطبيق".

جافا

@Override
public void onStart(@NonNull LifecycleOwner owner) {
  DefaultLifecycleObserver.super.onStart(owner);
  // Show the ad (if available) when the app moves to foreground.
  appOpenAdManager.showAdIfAvailable(currentActivity);
}
MyApplication.java

Kotlin

override fun onStart(owner: LifecycleOwner) {
  super.onStart(owner)
  currentActivity?.let {
    // Show the ad (if available) when the app moves to foreground.
    appOpenAdManager.showAdIfAvailable(it)
  }
}
MyApplication.kt

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

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

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

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

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

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

اعرض أول "إعلان على شاشة فتح التطبيق" بعد أن يستخدم المستخدمون تطبيقك بضع مرات.
يمكنك عرض "الإعلانات على شاشة فتح التطبيق" في الأوقات التي ينتظر فيها المستخدمون تحميل تطبيقك.
إذا كانت لديك شاشة تحميل تحت "الإعلان على شاشة فتح التطبيق"، واكتمل تحميل شاشة التحميل قبل إغلاق الإعلان، قد تحتاج إلى إغلاق شاشة التحميل في طريقة onAdDismissedFullScreenContent().

أمثلة على GitHub

مثال على "الإعلانات على شاشة فتح التطبيق": Java | Kotlin

الخطوات التالية

استكشِف المواضيع التالية:

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

المتطلبات الأساسية

اختبِر دائمًا باستخدام الإعلانات الاختبارية

توسيع فئة Application

جافا

Kotlin

تنفيذ مكوّن الأداة المساعدة

جافا

Kotlin

تحميل إعلان

جافا

Kotlin

عرض الإعلان

جافا

Kotlin

ضبط FullScreenContentCallback

جافا

Kotlin

مراعاة انتهاء صلاحية الإعلانات

جافا

Kotlin

تتبُّع النشاط الحالي

جافا

Kotlin

الاستماع إلى أحداث فتح التطبيق

إضافة المكتبات إلى ملف gradle

Kotlin

Groovy

تنفيذ واجهة مراقبة مراحل النشاط

جافا

Kotlin

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

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

أمثلة على GitHub

الخطوات التالية

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