کیت توسعه نرم‌افزاری تبلیغات موبایلی گوگل (Google Mobile Ads SDK) در حالت تعمیر و نگهداری است. برای دریافت آخرین به‌روزرسانی‌ها و ویژگی‌ها، کیت توسعه نرم‌افزاری نسل بعدی GMA را منتقل و راه‌اندازی کنید.

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

آگهی‌های در صفحه باز شدن برنامه

پلاتفرم را انتخاب کنید: Android iOS Unity Flutter Android (Legacy)

این راهنما برای ناشرانی است که آگهی‌های باز شدن برنامه را بااستفاده از 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

مراحل بعدی

آگهی‌های در صفحه باز شدن برنامه