هذا الدليل مخصّص للناشرين الذين يدمجون "الإعلانات على شاشة فتح التطبيق" باستخدام 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();
}
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()
}
بعد ذلك، أضِف الرمز التالي إلى 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() {}
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 = 0
لاستخدام AppOpenAdManager، يمكنك استدعاء طرق برنامج تضمين البيانات العامة في مثيل MyApplication الفردي. تتفاعل فئة Application مع بقية الرمز، وتفوّض عمل تحميل الإعلان وعرضه إلى المدير.
تحميل إعلان
الخطوة التالية هي ملء طريقة loadAd ومعالجة عمليات الاستدعاء
لتحميل الإعلان.
جافا
Kotlin
استبدِل 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);
}
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)
}
ضبط 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.");
}
});
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.")
}
}
مراعاة انتهاء صلاحية الإعلانات
للتأكّد من عدم عرض إعلان منتهي الصلاحية، أضِف طريقة إلى
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);
}
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)
}
تتبُّع النشاط الحالي
لعرض الإعلان، يجب أن يكون سياق 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) {}
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) {}
يتيح لك 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);
}
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)
}
}
التشغيل على البارد وشاشات التحميل
تفترض المستندات حتى الآن أنّك تعرض "الإعلانات على شاشة فتح التطبيق" فقط عندما يفتح المستخدمون تطبيقك في المقدّمة بعد أن كان معلّقًا في الذاكرة. تحدث "عمليات التشغيل على البارد" عند تشغيل تطبيقك ولكن لم يتم تعليقه مسبقًا في الذاكرة.
ومن الأمثلة على التشغيل على البارد عندما يفتح المستخدم تطبيقك لأول مرة. في حالات التشغيل على البارد، لن يكون لديك "إعلان على شاشة فتح التطبيق" تم تحميله مسبقًا وجاهز للعرض على الفور. قد يؤدي التأخير بين طلب الإعلان وتلقّيه إلى موقف يتمكّن فيه المستخدمون من استخدام تطبيقك لفترة وجيزة قبل أن يفاجأوا بإعلان خارج السياق. تجنَّب ذلك لأنّه يقدّم تجربة سيئة للمستخدم.
الطريقة المفضّلة لاستخدام "الإعلانات على شاشة فتح التطبيق" عند التشغيل على البارد هي استخدام شاشة تحميل لتحميل مواد عرض لعبتك أو تطبيقك، وعرض الإعلان من شاشة التحميل فقط. إذا انتهى تطبيقك من التحميل وأرسل المستخدم إلى المحتوى الرئيسي لتطبيقك، لا تعرض الإعلان.
أفضل الممارسات
تساعدك "الإعلانات على شاشة فتح التطبيق" في تحقيق الربح من شاشة تحميل تطبيقك، عند تشغيل التطبيق لأول مرة وأثناء التبديل بين التطبيقات، ولكن من المهم مراعاة أفضل الممارسات حتى يستمتع المستخدمون باستخدام تطبيقك. من الأفضل:
- اعرض أول "إعلان على شاشة فتح التطبيق" بعد أن يستخدم المستخدمون تطبيقك بضع مرات.
- يمكنك عرض "الإعلانات على شاشة فتح التطبيق" في الأوقات التي ينتظر فيها المستخدمون تحميل تطبيقك.
- إذا كانت لديك شاشة تحميل تحت "الإعلان على شاشة فتح التطبيق"، واكتمل تحميل شاشة التحميل قبل إغلاق الإعلان، قد تحتاج إلى إغلاق شاشة التحميل في طريقة
onAdDismissedFullScreenContent().
أمثلة على GitHub
الخطوات التالية
استكشِف المواضيع التالية: