این راهنما برای ناشران در نظر گرفته شده است که تبلیغات باز برنامه را با استفاده از Google Mobile Ads Android SDK یکپارچه می کنند.
تبلیغات باز برنامه یک قالب تبلیغاتی ویژه است که برای ناشرانی که مایل به کسب درآمد از صفحه بارگذاری برنامه خود هستند در نظر گرفته شده است. تبلیغات باز برنامه را می توان در هر زمان بسته کرد، و به گونه ای طراحی شده اند که وقتی کاربران برنامه شما را در پیش زمینه می آورند، نمایش داده می شوند.
آگهیهای باز برنامه بهطور خودکار ناحیه کوچکی از نام تجاری را نشان میدهد تا کاربران بدانند که در برنامه شما هستند. در اینجا نمونه ای از ظاهر یک تبلیغ باز برنامه آمده است:
در سطح بالا این مراحل مهم هستند:
- کلاس
Application
را گسترش دهید تا Google Mobile Ads SDK مقداردهی شود. - یک کلاس ابزاری ایجاد کنید که قبل از نیاز به نمایش آگهی، آن را بارگذاری کند.
- یک تبلیغ را بارگیری کنید.
- به
ActivityLifecycleCallbacks.
- نمایش آگهی و رسیدگی به تماس ها.
- رابط
LifecycleObserver
را برای نمایش آگهی در طول رویدادهای پیش زمینه پیاده سازی و ثبت کنید.
پیش نیازها
- Google Mobile Ads SDK 19.4.0 یا بالاتر.
- دستورالعمل های راه اندازی را در راهنمای شروع کار دنبال کنید.
همیشه با تبلیغات آزمایشی تست کنید
هنگام ساخت و آزمایش برنامه های خود، مطمئن شوید که از تبلیغات آزمایشی به جای تبلیغات زنده و تولیدی استفاده می کنید. عدم انجام این کار می تواند منجر به تعلیق حساب شما شود.
ساده ترین راه برای بارگیری تبلیغات آزمایشی استفاده از شناسه واحد آگهی آزمایشی اختصاصی ما برای تبلیغات باز برنامه است:
ca-app-pub-3940256099942544/3419835294
این بهطور ویژه پیکربندی شده است تا تبلیغات آزمایشی را برای هر درخواست بازگرداند، و شما میتوانید هنگام کدنویسی، آزمایش و اشکالزدایی از آن در برنامههای خود استفاده کنید. فقط مطمئن شوید که قبل از انتشار برنامه خود، آن را با شناسه واحد تبلیغاتی خود جایگزین کرده اید.
برای اطلاعات بیشتر درباره نحوه عملکرد تبلیغات آزمایشی SDK تبلیغات موبایل، به آگهیهای آزمایشی مراجعه کنید.
کلاس Application را گسترش دهید
یک کلاس جدید ایجاد کنید که کلاس Application
را گسترش دهد و کد زیر را برای مقداردهی اولیه Google Mobile Ads SDK اضافه کنید.
جاوا
/** Application class that initializes, loads and show ads when activities change states. */ public class MyApplication extends Application { @Override public void onCreate() { super.onCreate(); MobileAds.initialize( this, new OnInitializationCompleteListener() { @Override public void onInitializationComplete(InitializationStatus initializationStatus) {} }); } }
کاتلین
/** Application class that initializes, loads and show ads when activities change states. */ class MyApplication : Application() { override fun onCreate() { super.onCreate() MobileAds.initialize(this) {} } }
این SDK را مقداردهی اولیه می کند و اسکلتی را ارائه می دهد که بعداً برای رویدادهای پیش زمینه برنامه ثبت نام می کنید.
سپس کد زیر را به AndroidManifest.xml
خود اضافه کنید:
<application
android:name="com.google.android.gms.example.appopendemo.MyApplication" ...>
...
</application>
حتماً به نام بسته واقعی خود اشاره کنید.
کلاس ابزار خود را پیاده سازی کنید
تبلیغ شما باید به سرعت نمایش داده شود، بنابراین بهتر است قبل از اینکه نیاز به نمایش آگهی خود داشته باشید آن را بارگذاری کنید. به این ترتیب، به محض ورود کاربر به برنامه شما، یک تبلیغ آماده خواهید داشت. یک کلاس کاربردی برای درخواست تبلیغات قبل از زمانی که نیاز به نمایش آگهی دارید، پیاده سازی کنید.
یک کلاس جدید به نام AppOpenAdManager
در کلاس MyApplication
کنید و آن را به صورت زیر پر کنید:
جاوا
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 = "ca-app-pub-3940256099942544/3419835294"; 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 below. } /** Check if ad exists and can be shown. */ private boolean isAdAvailable() { return appOpenAd != null; } } }
کاتلین
private const val String LOG_TAG = "AppOpenAdManager" private const val String AD_UNIT_ID = "ca-app-pub-3940256099942544/3419835294" 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 below. } /** Check if ad exists and can be shown. */ private fun isAdAvailable(): Boolean { return appOpenAd != null } } }
اکنون که یک کلاس ابزار دارید، می توانید آن را در کلاس MyApplication
خود نمونه سازی کنید:
جاوا
public class MyApplication extends Application { private AppOpenAdManager appOpenAdManager; @Override public void onCreate() { super.onCreate(); MobileAds.initialize( this, new OnInitializationCompleteListener() { @Override public void onInitializationComplete(InitializationStatus initializationStatus) {} }); appOpenAdManager = new AppOpenAdManager(this); } }
کاتلین
class MyApplication : Application() { private lateinit var appOpenAdManager: AppOpenAdManager override fun onCreate() { super.onCreate() MobileAds.initialize(this) {} appOpenAdManager = AppOpenAdManager() } }
یک تبلیغ را بارگیری کنید
مرحله بعدی پر کردن loadAd()
است.
جاوا
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; } @Override public void onAdFailedToLoad(LoadAdError loadAdError) { // Called when an app open ad has failed to load. Log.d(LOG_TAG, loadAdError.getMessage()); isLoadingAd = false; } }); } ... }
کاتلین
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 } override fun onAdFailedToLoad(loadAdError: LoadAdError) { // Called when an app open ad has failed to load. Log.d(LOG_TAG, loadAdError.message) isLoadingAd = false; } }) } ... }
AppOpenAdLoadCallback
دارد که پس از اتمام بارگیری AppOpenAd
می شوند.
فعالیت فعلی را پیگیری کنید
برای نمایش آگهی، به یک زمینه Activity
نیاز دارید. برای پیگیری آخرین فعالیتی که کاربر شما استفاده می کند، Application.ActivityLifecycleCallbacks
را در کلاس Application
خود پیاده سازی کنید.
جاوا
public class MyApplication extends Application implements ActivityLifecycleCallbacks { private Activity currentActivity; ... /** ActivityLifecycleCallback methods. */ @Override public void onActivityCreated(Activity activity, Bundle savedInstanceState) {} @Override public void onActivityStarted(Activity activity) { // Updating the currentActivity only when an ad is not showing. if (!appOpenAdManager.isShowingAd) { 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) {} }
کاتلین
class MyApplication : Application(), Application.ActivityLifecycleCallbacks { private var currentActivity: Activity? = null ... /** ActivityLifecycleCallback methods. */ override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {} override fun onActivityStarted(activity: Activity) { // Updating the currentActivity only when an ad is not showing. 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
کنید.
جاوا
public class MyApplication extends Application { ... @Override public void onCreate() { super.onCreate(); this.registerActivityLifecycleCallbacks(this); MobileAds.initialize( this, new OnInitializationCompleteListener() { @Override public void onInitializationComplete(InitializationStatus initializationStatus) {} }); appOpenAdManager = new AppOpenAdManager(); } }
کاتلین
class MyApplication : Application() { ... override fun onCreate() { super.onCreate() registerActivityLifecycleCallbacks(this) MobileAds.initialize(this) {} appOpenAdManager = AppOpenAdManager() } }
registerActivityLifecycleCallbacks
به شما امکان می دهد به تمام رویدادهای Activity
گوش دهید. با گوش دادن به زمان شروع و نابودی فعالیتها، میتوانید مرجعی به Activity
فعلی را پیگیری کنید که سپس از آن برای ارائه آگهی باز برنامه خود استفاده خواهید کرد.
نمایش آگهی و مدیریت رویدادهای پاسخ به تماس تمام صفحه
کد زیر زمان نمایش و سپس بارگذاری مجدد آگهی را نشان می دهد.
جاوا
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.fullScreenContentCallback( 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); } ... } }
کاتلین
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
رویدادهایی مانند زمانی که تبلیغ ارائه میشود، نمایش داده نمیشود یا زمانی که رد میشود مدیریت میکند. اگر کاربر پس از خروج از برنامه شما با کلیک بر روی یک تبلیغ باز برنامه به آن بازگردد، مطمئن می شود که با تبلیغ باز برنامه دیگری به او نمایش داده نمی شود.
به رویدادهای پیش زمینه برنامه گوش دهید
کتابخانه ها را به فایل gradle خود اضافه کنید
برای اینکه از رویدادهای پیش زمینه برنامه مطلع شوید، باید LifecycleObserver
را ثبت کنید. ابتدا، فایل build.gradle
در سطح برنامه خود را ویرایش کنید تا شامل کتابخانه های LifecycleObserver
شود:
apply plugin: 'com.android.application'
dependencies {
implementation 'androidx.appcompat:appcompat:1.3.0'
implementation 'androidx.constraintlayout:constraintlayout:2.0.4'
implementation 'com.google.android.gms:play-services-ads:21.1.0'
def lifecycle_version = "2.3.1"
implementation "androidx.lifecycle:lifecycle-extensions:$lifecycle_version"
implementation "androidx.lifecycle:lifecycle-runtime:$lifecycle_version"
annotationProcessor "androidx.lifecycle:lifecycle-compiler:$lifecycle_version"
}
رابط LifecycleObserver را پیاده سازی کنید
می توانید با اجرای رابط LifecycleObserver
به رویدادهای پیش زمینه در کلاس Application
گوش دهید.
جاوا
public class MyApplication extends Application implements ActivityLifecycleCallbacks, LifecycleObserver { { ... @Override public void onCreate() { super.onCreate(); this.registerActivityLifecycleCallbacks(this); MobileAds.initialize( this, new OnInitializationCompleteListener() { @Override public void onInitializationComplete(InitializationStatus initializationStatus) {} }); 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. } }); } }
کاتلین
class MyApplication : Application(), Application.ActivityLifecycleCallbacks, LifecycleObserver { ... override fun onCreate() { super.onCreate() registerActivityLifecycleCallbacks(this) MobileAds.initialize(this) {} 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. } }) } }
با ثبت LifecycleObserver
، برنامه شما از راهاندازی برنامه و رویدادهای پیشزمینه آگاه میشود و میتواند آگهی را در زمانهای مناسب نشان دهد.
انقضای آگهی را در نظر بگیرید
برای اطمینان از اینکه تبلیغ منقضی شده ای را نشان نمی دهید، روشی را به AppOpenAdManager
اضافه کنید که بررسی می کند چقدر از زمان بارگیری مرجع تبلیغ شما گذشته است. سپس، از این روش برای بررسی اینکه آیا تبلیغ هنوز معتبر است یا خیر، استفاده کنید.
جاوا
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; /** 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; } }); } ... /** 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); } }
کاتلین
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 /** 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; } }) } ... private fun wasLoadTimeLessThanNHoursAgo(numHours: Long): Boolean { val dateDifference: Long = Date().time - loadTime val numMilliSecondsPerHour: Long = 3600000 return dateDifference < numMilliSecondsPerHour * numHours } private fun isAdAvailable(): Boolean { return appOpenAd != null && wasLoadTimeLessThanNHoursAgo(4) } }
صفحه نمایش های شروع و بارگذاری سرد
مستندات تا کنون فرض میکنند که شما فقط زمانی تبلیغات باز برنامه را نشان میدهید که کاربران برنامه شما را در جلوی تصویر قرار میدهند، زمانی که در حافظه تعلیق شده باشد. "شروع سرد" زمانی رخ می دهد که برنامه شما راه اندازی می شود اما قبلاً در حافظه تعلیق نشده بود.
یک مثال از شروع سرد زمانی است که کاربر برای اولین بار برنامه شما را باز می کند. با شروع سرد، شما یک تبلیغ باز برنامه بارگیری شده قبلی نخواهید داشت که فوراً برای نمایش آماده باشد. تأخیر بین درخواست تبلیغ و دریافت مجدد آگهی میتواند موقعیتی را ایجاد کند که کاربران بتوانند قبل از غافلگیری از یک آگهی خارج از زمینه، به طور خلاصه از برنامه شما استفاده کنند. این باید اجتناب شود زیرا تجربه کاربری بدی است.
روش ترجیحی برای استفاده از تبلیغات باز برنامه در شروع سرد این است که از صفحه بارگیری برای بارگیری دارایی های بازی یا برنامه خود استفاده کنید و فقط تبلیغ را از صفحه بارگیری نشان دهید. اگر برنامه شما بارگیری کامل شده است و کاربر را به محتوای اصلی برنامه شما فرستاده است، تبلیغ را نشان ندهید.
بهترین شیوه ها
تبلیغات باز برنامه به شما کمک می کند تا از صفحه بارگیری برنامه خود کسب درآمد کنید، در اولین راه اندازی برنامه و در حین جابجایی برنامه، اما مهم است که بهترین شیوه ها را در نظر داشته باشید تا کاربران از استفاده از برنامه شما لذت ببرند. بهتر است:
- اولین تبلیغ باز برنامه خود را بعد از اینکه کاربران چند بار از برنامه شما استفاده کردند نشان دهید.
- تبلیغات باز برنامه را در مواقعی نشان دهید که کاربران شما در غیر این صورت منتظر بارگیری برنامه شما هستند.
- اگر صفحه بارگیری زیر آگهی باز برنامه دارید و صفحه بارگیری شما قبل از رد شدن آگهی بارگیری کامل می شود، ممکن است بخواهید صفحه بارگیری خود را با روش
onAdDismissedFullScreenContent()
رد کنید.