‫Google Mobile Ads SDK נמצא במצב תחזוקה. כדי ליהנות מהעדכונים והתכונות האחרונים, כדאי migrate ל-GMA Next-Gen SDK ולהגדיר אותו.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

מודעות בפתיחת האפליקציה

בחירת פלטפורמה: Android iOS Unity Flutter Android (גרסה קודמת)

המדריך הזה מיועד לבעלי אפליקציות שמשלבים מודעות בפתיחת אפליקציה באמצעות Google Mobile Ads SDK (Legacy).

מודעות בפתיחת האפליקציה הן פורמט מודעה מיוחד שמיועד לבעלי אפליקציות שרוצים לייצר הכנסות ממסכי הטעינה של האפליקציה. מודעות בפתיחת אפליקציה ניתנות לסגירה בכל שלב, והן מתוכננות להופיע כשהמשתמשים מעבירים את האפליקציה לחזית.

במודעות בפתיחת האפליקציה מוצג באופן אוטומטי אזור מיתוג קטן, כדי שהמשתמשים ידעו שהם נמצאים באפליקציה שלכם. הנה דוגמה למודעה בפתיחת האפליקציה:

דרישות מוקדמות

תמיד צריך לבדוק באמצעות מודעות בדיקה

כשאתם מפתחים ובודקים את האפליקציות, חשוב להשתמש במודעות בדיקה ולא במודעות פעילות. אחרת, אנחנו עלולים להשעות את החשבון.

הדרך הכי קלה לטעון מודעות לבדיקה היא להשתמש במזהה יחידת המודעות הייעודי לבדיקה של מודעות בפתיחת האפליקציה:

ca-app-pub-3940256099942544/9257395921

הוא הוגדר במיוחד כדי להחזיר מודעות בדיקה לכל בקשה, ואתם יכולים להשתמש בו באפליקציות שלכם בזמן התכנות, הבדיקה וניפוי הבאגים. רק חשוב להחליף אותו במזהה יחידת המודעות שלכם לפני שמפרסמים את האפליקציה.

מידע נוסף על אופן הפעולה של מודעות בדיקה ב-Google Mobile Ads SDK (Legacy) זמין במאמר הפעלת מודעות בדיקה.

הרחבת המחלקה Application

יוצרים מחלקה חדשה שמרחיבה את המחלקה Application. כך אפשר לנהל מודעות שקשורות למצב של האפליקציה, ולא רק ל-Activity יחיד, בהתאם למחזור החיים:

Java

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 כדי להכיל את העבודה שקשורה לטעינה ולהצגה של מודעות בפתיחת האפליקציה:

Java

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, צריך להפעיל את ה-wrapper methods הציבוריות במופע ה-singleton של MyApplication. המחלקה Application מתממשקת עם שאר הקוד, ומעבירה את העבודה של טעינת המודעה והצגתה למנהל.

טעינת מודעה

השלב הבא הוא למלא את השיטה loadAd ולטפל בקריאות החוזרות (callbacks) של טעינת המודעה.

Java

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 במזהה יחידת המודעות.

הצגת המודעה

ההטמעה הנפוצה ביותר של מודעות בפתיחת האפליקציה היא לנסות להציג מודעה בפתיחת האפליקציה בסמוך להפעלת האפליקציה, להפעיל את תוכן האפליקציה אם המודעה לא מוכנה, ולטעון מראש מודעה אחרת להזדמנות הבאה של פתיחת האפליקציה. דוגמאות להטמעה מפורטות בהנחיות לשימוש במודעות בפתיחת אפליקציה.

הקוד הבא מציג מודעה ולאחר מכן טוען אותה מחדש:

Java

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, חשוב להגדיר את הקריאה החוזרת (callback):

Java

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 שיטה שבודקת כמה זמן עבר מאז שנטען קובץ העזר של המודעה. לאחר מכן, משתמשים בשיטה הזו כדי לבדוק אם המודעה עדיין תקינה.

Java

/** 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 ולהטמיע אותו.

Java

@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. מוסיפים את התלות שלו לקובץ ה-build ברמת האפליקציה:

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() כדי להציג את המודעה בפתיחת האפליקציה.

Java

@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

הפעלות במצב התחלתי (cold start) ומסכי טעינה

ההנחיות עד עכשיו מתייחסות למצב שבו המודעות בפתיחת האפליקציה מוצגות רק כשהמשתמשים מעבירים את האפליקציה לחזית כשהיא מושהית בזיכרון. "הפעלות קרות" מתרחשות כשהאפליקציה מופעלת אבל לא הושעתה קודם בזיכרון.

דוגמה להפעלה במצב התחלתי היא כשמשתמש פותח את האפליקציה בפעם הראשונה. בהפעלה במצב התחלתי, אין מודעה בפתיחת האפליקציה שנטענה מראש ומוכנה להצגה מיידית. העיכוב בין בקשת המודעה לבין קבלת המודעה יכול ליצור מצב שבו המשתמשים יכולים להשתמש באפליקציה לזמן קצר, ואז פתאום מופיעה מודעה שלא קשורה להקשר. כדאי להימנע מכך כי זה פוגע בחוויית המשתמש.

הדרך המועדפת להשתמש במודעות בפתיחת האפליקציה בהפעלות קרות היא להשתמש במסך טעינה כדי לטעון את נכסי המשחק או האפליקציה, ולהציג את המודעה רק ממסך הטעינה. אם האפליקציה סיימה להיטען והמשתמש הועבר לתוכן הראשי שלה, אל תציגו את המודעה.

שיטות מומלצות

מודעות בפתיחת האפליקציה עוזרות לכם לייצר הכנסות ממסך הטעינה של האפליקציה, כשהאפליקציה מופעלת בפעם הראשונה ובמהלך מעבר בין אפליקציות. עם זאת, חשוב לזכור את השיטות המומלצות כדי שהמשתמשים ייהנו מהשימוש באפליקציה. מומלץ:

הציגו את המודעה הראשונה בפתיחת האפליקציה אחרי שהמשתמשים השתמשו באפליקציה כמה פעמים.
כדאי להציג מודעות בפתיחת האפליקציה בזמנים שבהם המשתמשים ממתינים שהאפליקציה תיטען.
אם יש לכם מסך טעינה מתחת למודעה בפתיחת האפליקציה, והטעינה של מסך הטעינה מסתיימת לפני שהמודעה נסגרת, יכול להיות שתרצו לסגור את מסך הטעינה ב-method‏ onAdDismissedFullScreenContent().

דוגמאות ב-GitHub

דוגמה למודעות בפתיחת האפליקציה: Java | Kotlin

השלבים הבאים

הנושאים הבאים:

מודעות בפתיחת האפליקציה קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

דרישות מוקדמות

תמיד צריך לבדוק באמצעות מודעות בדיקה

הרחבת המחלקה Application

Java

Kotlin

הטמעת רכיב התשתית

Java

Kotlin

טעינת מודעה

Java

Kotlin

הצגת המודעה

Java

Kotlin

הגדרת FullScreenContentCallback

Java

Kotlin

כדאי להביא בחשבון את תפוגת התוקף של המודעות

Java

Kotlin

מעקב אחרי הפעילות הנוכחית

Java

Kotlin

האזנה לאירועים של אפליקציות שפועלות בחזית

הוספת הספריות לקובץ Gradle

Kotlin

Groovy

הטמעה של ממשק הצופה במחזור החיים

Java

Kotlin

הפעלות במצב התחלתי (cold start) ומסכי טעינה

שיטות מומלצות

דוגמאות ב-GitHub

השלבים הבאים

מודעות בפתיחת האפליקציה