هذا الدليل مخصّص للناشرين الذين يدمجون الإعلانات على شاشة فتح التطبيق باستخدام حزمة تطوير البرامج (SDK) لميزة "إعلانات Google على الأجهزة الجوّالة".
"الإعلانات على شاشة فتح التطبيق" هي تنسيق إعلان خاص مخصّص للناشرين الذين يريدون تحقيق الربح من شاشات تحميل تطبيقاتهم. يمكن إغلاق "الإعلانات على شاشة فتح التطبيق" في أي وقت، وهي مصمّمة لعرضها عندما ينقل المستخدمون تطبيقك إلى المقدّمة.
تعرض "الإعلانات على شاشة فتح التطبيق" تلقائيًا مساحة صغيرة خاصة بالعناصر البصرية للعلامة التجارية كي يعرف المستخدمون أنّهم داخل تطبيقك. في ما يلي مثال على شكل "الإعلان على شاشة فتح التطبيق":
المتطلبات الأساسية
- أكمِل دليل البدء.
إجراء الاختبار دائمًا باستخدام الإعلانات الاختبارية
عند إنشاء تطبيقاتك واختبارها، احرص على استخدام إعلانات اختبارية بدلاً من الإعلانات المنشورة. وقد يؤدي عدم إجراء ذلك إلى تعليق حسابك.
إنّ الطريقة الأسهل لتحميل الإعلانات الاختبارية هي استخدام معرّف الوحدة الإعلانية الاختبارية المخصّص للإعلانات المفتوحة في التطبيقات:
/21775744923/example/app-open
تم إعداده خصيصًا لعرض إعلانات اختبارية لكل طلب، ويمكنك استخدامه في تطبيقاتك أثناء الترميز والاختبار وتحديد الأخطاء وإصلاحها. ما عليك سوى التأكّد من استبداله بمعرّف وحدتك الإعلانية قبل نشر تطبيقك.
لمزيد من المعلومات عن آلية عمل الإعلانات الاختبارية في حزمة "SDK لإعلانات Google على الأجهزة الجوّالة"، اطّلِع على مقالة تفعيل الإعلانات الاختبارية.
توسيع فئة التطبيق
أنشئ فئة جديدة تمدّد فئة Application
، وأضِف الرمز التالي
لإعداد حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" عند بدء تشغيل تطبيقك.
Java
/** Application class that initializes, loads and show ads when activities change states. */
public class MyApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
new Thread(
() -> {
// Initialize the Google Mobile Ads SDK on a background thread.
MobileAds.initialize(this, initializationStatus -> {});
})
.start();
}
}
Kotlin
/** Application class that initializes, loads and show ads when activities change states. */
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
val backgroundScope = CoroutineScope(Dispatchers.IO)
backgroundScope.launch {
// Initialize the Google Mobile Ads SDK on a background thread.
MobileAds.initialize(this@MyApplication) {}
}
}
}
يؤدي ذلك إلى بدء حزمة تطوير البرامج (SDK) وتوفير الهيكل الذي ستسجّل فيه لاحقًا لأحداث عرض التطبيق في المقدّمة.
بعد ذلك، أضِف الرمز التالي إلى AndroidManifest.xml
:
<!-- TODO: Update to reference your actual package name. -->
<application
android:name="com.google.android.gms.example.appopendemo.MyApplication" ...>
...
</application>
تنفيذ مكوّن التطبيق
من المفترض أن يظهر إعلانك بسرعة، لذا من الأفضل تحميل إعلانك قبل أن تحتاج إلى عرضه. بهذه الطريقة، سيكون لديك إعلان جاهز للعرض فور دخول المستخدِم إلى تطبيقك.
نفِّذ مكوّنًا خدميًا AppOpenAdManager
لتقديم طلبات الإعلانات قبل
وقت عرض الإعلان.
Java
public class MyApplication extends Application {
// ...
/** Inner class that loads and shows app open ads. */
private class AppOpenAdManager {
private static final String LOG_TAG = "AppOpenAdManager";
private static final String AD_UNIT_ID = "/21775744923/example/app-open";
private AppOpenAd appOpenAd = null;
private boolean isLoadingAd = false;
private boolean isShowingAd = false;
/** Constructor. */
public AppOpenAdManager() {}
/** Request an ad. */
private void loadAd(Context context) {
// We will implement this later.
}
/** Check if ad exists and can be shown. */
private boolean isAdAvailable() {
return appOpenAd != null;
}
}
}
Kotlin
private const val String LOG_TAG = "AppOpenAdManager"
private const val String AD_UNIT_ID = "/21775744923/example/app-open"
public class MyApplication extends Application {
// ...
/** Inner class that loads and shows app open ads. */
private inner class AppOpenAdManager {
private var appOpenAd: AppOpenAd? = null
private var isLoadingAd = false
var isShowingAd = false
/** Request an ad. */
fun loadAd(context: Context) {
// We will implement this later.
}
/** Check if ad exists and can be shown. */
private fun isAdAvailable(): Boolean {
return appOpenAd != null
}
}
}
الآن بعد أن أصبحت لديك فئة أدوات، يمكنك إنشاء مثيل لها في فئة
MyApplication
:
Java
public class MyApplication extends Application {
private AppOpenAdManager appOpenAdManager;
@Override
public void onCreate() {
super.onCreate();
new Thread(
() -> {
// Initialize the Google Mobile Ads SDK on a background thread.
MobileAds.initialize(this, initializationStatus -> {});
})
.start();
appOpenAdManager = new AppOpenAdManager(this);
}
}
Kotlin
class MyApplication : Application() {
private lateinit var appOpenAdManager: AppOpenAdManager
override fun onCreate() {
super.onCreate()
val backgroundScope = CoroutineScope(Dispatchers.IO)
backgroundScope.launch {
// Initialize the Google Mobile Ads SDK on a background thread.
MobileAds.initialize(this@MyApplication) {}
}
appOpenAdManager = AppOpenAdManager()
}
}
تحميل إعلان
الخطوة التالية هي ملء طريقة loadAd()
ومعالجة callbacks لتحميل الإعلان.
Java
private class AppOpenAdManager {
// ...
/** Request an ad. */
public void loadAd(Context context) {
// Do not load ad if there is an unused ad or one is already loading.
if (isLoadingAd || isAdAvailable()) {
return;
}
isLoadingAd = true;
AdRequest request = new AdRequest.Builder().build();
AppOpenAd.load(
context, AD_UNIT_ID, request,
AppOpenAd.APP_OPEN_AD_ORIENTATION_PORTRAIT,
new AppOpenAdLoadCallback() {
@Override
public void onAdLoaded(AppOpenAd ad) {
// Called when an app open ad has loaded.
Log.d(LOG_TAG, "Ad was 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, loadAdError.getMessage());
isLoadingAd = false;
}
});
}
// ...
}
Kotlin
private inner class AppOpenAdManager {
// ...
/** Request an ad. */
fun loadAd(context: Context) {
// Do not load ad if there is an unused ad or one is already loading.
if (isLoadingAd || isAdAvailable()) {
return
}
isLoadingAd = true
val request = AdRequest.Builder().build()
AppOpenAd.load(
context, AD_UNIT_ID, request,
AppOpenAd.APP_OPEN_AD_ORIENTATION_PORTRAIT,
object : AppOpenAdLoadCallback() {
override fun onAdLoaded(ad: AppOpenAd) {
// Called when an app open ad has loaded.
Log.d(LOG_TAG, "Ad was 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, loadAdError.message)
isLoadingAd = false;
}
})
}
// ...
}
عرض الإعلان ومعالجة أحداث معاودة الاتصال بملء الشاشة
إنّ الطريقة الأكثر شيوعًا لتنفيذ الإعلانات على شاشة فتح التطبيق هي محاولة عرض إعلان على شاشة فتح التطبيق بالقرب من وقت إطلاق التطبيق، وبدء عرض محتوى التطبيق إذا لم يكن الإعلان جاهزًا، وتحميل إعلان آخر مسبقًا لعرضه في فرصة فتح التطبيق التالية. اطّلِع على إرشادات بشأن الإعلانات على شاشة فتح التطبيق للحصول على أمثلة على التنفيذ.
يوضّح الرمز البرمجي التالي كيفية عرض إعلان وإعادة تحميله لاحقًا:
Java
public class MyApplication extends Application {
// ...
/** Interface definition for a callback to be invoked when an app open ad is complete. */
public interface OnShowAdCompleteListener {
void onShowAdComplete();
}
private class AppOpenAdManager {
// ...
/** Shows the ad if one isn't already showing. */
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(LOG_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 (!isAdAvailable()) {
Log.d(LOG_TAG, "The app open ad is not ready yet.");
onShowAdCompleteListener.onShowAdComplete();
loadAd(activity);
return;
}
appOpenAd.setFullScreenContentCallback(
new FullScreenContentCallback() {
@Override
public void onAdDismissedFullScreenContent() {
// Called when fullscreen content is dismissed.
// Set the reference to null so isAdAvailable() returns false.
Log.d(LOG_TAG, "Ad dismissed fullscreen content.");
appOpenAd = null;
isShowingAd = false;
onShowAdCompleteListener.onShowAdComplete();
loadAd(activity);
}
@Override
public void onAdFailedToShowFullScreenContent(AdError adError) {
// Called when fullscreen content failed to show.
// Set the reference to null so isAdAvailable() returns false.
Log.d(LOG_TAG, adError.getMessage());
appOpenAd = null;
isShowingAd = false;
onShowAdCompleteListener.onShowAdComplete();
loadAd(activity);
}
@Override
public void onAdShowedFullScreenContent() {
// Called when fullscreen content is shown.
Log.d(LOG_TAG, "Ad showed fullscreen content.");
}
});
isShowingAd = true;
appOpenAd.show(activity);
}
// ...
}
}
Kotlin
class MyApplication : Application() {
// ...
/** Interface definition for a callback to be invoked when an app open ad is complete. */
interface OnShowAdCompleteListener {
fun onShowAdComplete()
}
private inner class AppOpenAdManager {
// ...
/** Shows the ad if one isn't already showing. */
fun showAdIfAvailable(
activity: Activity,
onShowAdCompleteListener: OnShowAdCompleteListener) {
// If the app open ad is already showing, do not show the ad again.
if (isShowingAd) {
Log.d(LOG_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 (!isAdAvailable()) {
Log.d(LOG_TAG, "The app open ad is not ready yet.")
onShowAdCompleteListener.onShowAdComplete()
loadAd(activity)
return
}
appOpenAd?.setFullScreenContentCallback(
object : FullScreenContentCallback() {
override fun onAdDismissedFullScreenContent() {
// Called when full screen content is dismissed.
// Set the reference to null so isAdAvailable() returns false.
Log.d(LOG_TAG, "Ad dismissed fullscreen content.")
appOpenAd = null
isShowingAd = false
onShowAdCompleteListener.onShowAdComplete()
loadAd(activity)
}
override fun onAdFailedToShowFullScreenContent(adError: AdError) {
// Called when fullscreen content failed to show.
// Set the reference to null so isAdAvailable() returns false.
Log.d(LOG_TAG, adError.message)
appOpenAd = null
isShowingAd = false
onShowAdCompleteListener.onShowAdComplete()
loadAd(activity)
}
override fun onAdShowedFullScreenContent() {
// Called when fullscreen content is shown.
Log.d(LOG_TAG, "Ad showed fullscreen content.")
}
})
isShowingAd = true
appOpenAd?.show(activity)
}
// ...
}
}
تعالج العلامة
FullScreenContentCallback
الأحداث، مثل وقت عرض الإعلان أو تعذُّر عرضه أو عند
إغلاقه.
يجب مراعاة مدة صلاحية الإعلان.
لضمان عدم عرض إعلان منتهي الصلاحية، أضِف طريقة إلى AppOpenAdManager
تحقّق من المدة التي انقضت منذ تحميل مرجع إعلانك. بعد ذلك، استخدِم هذه المحاولة للتحقّق مما إذا كان الإعلان لا يزال صالحًا.
Java
private class AppOpenAdManager {
// ...
/** Keep track of the time an app open ad is loaded to ensure you don't show an expired ad. */
private long loadTime = 0;
// ...
/** Utility method to check if ad was loaded more than n hours ago. */
private boolean wasLoadTimeLessThanNHoursAgo(long numHours) {
long dateDifference = (new Date()).getTime() - this.loadTime;
long numMilliSecondsPerHour = 3600000;
return (dateDifference < (numMilliSecondsPerHour * numHours));
}
/** Check if ad exists and can be shown. */
public boolean isAdAvailable() {
return appOpenAd != null && wasLoadTimeLessThanNHoursAgo(4);
}
}
Kotlin
private inner class AppOpenAdManager {
// ...
/** 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;
// ...
/** Utility method to 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 {
return appOpenAd != null && wasLoadTimeLessThanNHoursAgo(4)
}
}
تتبُّع النشاط الحالي
لعرض الإعلان، ستحتاج إلى سياق Activity
. لتتبُّع
النشاط الأكثر استخدامًا حاليًا، سجِّل في Application.ActivityLifecycleCallbacks
ونفِّذ الخطوات الواردة فيه.
Java
public class MyApplication extends Application implements ActivityLifecycleCallbacks {
private Activity currentActivity;
@Override
public void onCreate() {
super.onCreate();
this.registerActivityLifecycleCallbacks(this);
// ...
}
/** ActivityLifecycleCallback methods. */
@Override
public void onActivityCreated(Activity activity, Bundle savedInstanceState) {}
@Override
public void onActivityStarted(Activity activity) {
currentActivity = activity
}
@Override
public void onActivityResumed(Activity activity) {}
@Override
public void onActivityStopped(Activity activity) {}
@Override
public void onActivityPaused(Activity activity) {}
@Override
public void onActivitySaveInstanceState(Activity activity, Bundle bundle) {}
@Override
public void onActivityDestroyed(Activity activity) {}
}
Kotlin
class MyApplication : Application(), Application.ActivityLifecycleCallbacks {
private var currentActivity: Activity? = null
override fun onCreate() {
super.onCreate()
registerActivityLifecycleCallbacks(this)
// ...
}
/** ActivityLifecycleCallback methods. */
override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {}
override fun onActivityStarted(activity: Activity) {
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:23.6.0") implementation("androidx.lifecycle:lifecycle-process:2.8.3") }
رائع
dependencies { implementation 'com.google.android.gms:play-services-ads:23.6.0' implementation 'androidx.lifecycle:lifecycle-process:2.8.3' }
تنفيذ واجهة مراقب دورة الحياة
يمكنك الاستماع إلى أحداث عرض التطبيقات في المقدّمة من خلال تنفيذ واجهة
DefaultLifecycleObserver
.
نفِّذ الحدث onStart
لعرض الإعلان المفتوح للتطبيق.
Java
public class MyApplication extends Application
implements ActivityLifecycleCallbacks, LifecycleObserver {
// ...
@Override
public void onCreate() {
super.onCreate();
this.registerActivityLifecycleCallbacks(this);
new Thread(
() -> {
// Initialize the Google Mobile Ads SDK on a background thread.
MobileAds.initialize(this, initializationStatus -> {});
})
.start();
ProcessLifecycleOwner.get().getLifecycle().addObserver(this);
appOpenAdManager = new AppOpenAdManager();
}
/** LifecycleObserver method that shows the app open ad when the app moves to foreground. */
@OnLifecycleEvent(Event.ON_START)
protected void onMoveToForeground() {
// Show the ad (if available) when the app moves to foreground.
appOpenAdManager.showAdIfAvailable(currentActivity);
}
/** Show the ad if one isn't already showing. */
private void showAdIfAvailable(@NonNull final Activity activity) {
showAdIfAvailable(
activity,
new OnShowAdCompleteListener() {
@Override
public void onShowAdComplete() {
// Empty because the user will go back to the activity that shows the ad.
}
});
}
}
Kotlin
class MyApplication : Application(),
Application.ActivityLifecycleCallbacks, LifecycleObserver {
// ...
override fun onCreate() {
super.onCreate()
registerActivityLifecycleCallbacks(this)
val backgroundScope = CoroutineScope(Dispatchers.IO)
backgroundScope.launch {
// Initialize the Google Mobile Ads SDK on a background thread.
MobileAds.initialize(this@MyApplication) {}
}
ProcessLifecycleOwner.get().lifecycle.addObserver(this)
appOpenAdManager = AppOpenAdManager()
}
/** LifecycleObserver method that shows the app open ad when the app moves to foreground. */
@OnLifecycleEvent(Lifecycle.Event.ON_START)
fun onMoveToForeground() {
// Show the ad (if available) when the app moves to foreground.
currentActivity?.let {
appOpenAdManager.showAdIfAvailable(it)
}
}
/** Show the ad if one isn't already showing. */
fun showAdIfAvailable(activity: Activity) {
showAdIfAvailable(
activity,
object : OnShowAdCompleteListener {
override fun onShowAdComplete() {
// Empty because the user will go back to the activity that shows the ad.
}
})
}
}
عمليات التشغيل المُجرّد وشاشات التحميل
حتى الآن، تفترض المستندات أنّك لا تعرض "الإعلانات على شاشة فتح التطبيق" إلا عندما يصعِّد المستخدمون تطبيقك إلى المقدّمة عندما يكون معلّقًا في الذاكرة. تحدث "عمليات البدء البارد" عند تشغيل تطبيقك ولكن لم يتم تعليقه في الذاكرة من قبل.
على سبيل المثال، عندما يفتح أحد المستخدمين تطبيقك لأول مرة، يكون ذلك مثالاً على بدء التشغيل من البارد. في عمليات التشغيل على البارد، لن يكون لديك إعلان على شاشة فتح التطبيق تم تحميله مسبقًا وجاهز لعرضه على الفور. إنّ التأخير بين وقت طلب إعلان ووقت تلقّيه يمكن أن يؤدي إلى ظهور إعلان خارج السياق أمام المستخدمين قبل أن يتمكنوا من استخدام تطبيقك لفترة قصيرة. يجب تجنُّب ذلك لأنّه يؤدي إلى تجربة سيئة للمستخدم.
إنّ الطريقة المفضّلة لاستخدام الإعلانات على شاشة فتح التطبيق عند التشغيل الأوّلي هي استخدام شاشة تحميل لتحميل مواد عرض اللعبة أو التطبيق، وعرض الإعلان فقط من شاشة التحميل. إذا اكتمل تحميل تطبيقك وأرسل المستخدم إلى المحتوى الرئيسي لتطبيقك، لا تعرض الإعلان.
أفضل الممارسات
تساعدك الإعلانات على شاشة فتح التطبيق في تحقيق الربح من شاشة تحميل تطبيقك عند بدء استخدامه لأول مرة وأثناء التبديل بين التطبيقات، ولكن من المهم مراعاة أفضل الممارسات كي يستمتع المستخدمون باستخدام تطبيقك. من الأفضل اتّباع ما يلي:
- اعرض إعلان فتح التطبيق الأول بعد أن يستخدم المستخدمون تطبيقك بضع مرّات.
- يمكنك عرض الإعلانات على شاشة فتح التطبيق خلال الأوقات التي ينتظر فيها المستخدمون تحميل تطبيقك.
- إذا كانت لديك شاشة تحميل أسفل الإعلان على شاشة فتح التطبيق، واكتملت عملية تحميل شاشة التحميل قبل إغلاق الإعلان، ننصحك بإغلاق
شاشة التحميل في الطريقة
onAdDismissedFullScreenContent()
.
أمثلة على GitHub
الخطوات التالية
يمكنك استكشاف المواضيع التالية: