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

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

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

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

במדריך הזה מוסבר איך לשלב מודעות בפתיחת האפליקציה באפליקציה ל-Android.

לפני שמתחילים

לפני שממשיכים, צריך לבצע את הפעולות הבאות:

  • מגדירים את GMA Next-Gen SDK.
  • משתמשים במזהה של יחידת המודעות לבדיקה ca-app-pub-3940256099942544/9257395921.
    • כשאתם מפתחים ובודקים את האפליקציה, חשוב להשתמש במודעות בדיקה ולא במודעות פעילות בשלב ההפקה. אם לא תשתמשו במזהה יחידת המודעות הייעודית לבדיקה, Google עלולה להשעות את החשבון שלכם.
    • לפני שמפרסמים את האפליקציה, צריך להחליף את המזהה הזה במזהה של יחידת המודעות.
    • פרטים על מודעות בדיקה ב-GMA Next-Gen SDK זמינים במאמר הפעלת מודעות בדיקה.

הסבר על טעינת מודעות מראש (בטא)

התכונה "טעינת מודעה מראש" ב-GMA Next-Gen SDK מבצעת טעינה ושמירה במטמון של מודעות באופן אוטומטי.

היתרונות של טעינת מודעות מראש:

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

התחלת טעינת מודעה מראש

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

בדוגמה הבאה אפשר לראות איך מתחילים לטעון מראש מודעות:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
AppOpenAdPreloader.start(adUnitId, preloadConfig)

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
AppOpenAdPreloader.start(adUnitId, preloadConfig);

מחליפים את AD_UNIT_ID במזהה יחידת המודעות.

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

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

אחזור והצגה של המודעה שנטענה מראש

לפני שמציגים את המודעה, צריך להפעיל את ה-method‏ pollAd. אל תשמרו את האובייקט של המודעה שנטענה מראש. כשמפעילים את השיטה pollAd, המערכת של GMA Next-Gen SDK מאחזרת מודעה זמינה וטוענת מראש באופן אוטומטי את המודעה הבאה ברקע. אם אין מודעה זמינה, GMA Next-Gen SDK לא מחזיר מודעות.

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

Kotlin

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = AppOpenAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "App open ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "App open ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : AppOpenAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "App open ad recorded an impression.")
      }
    }
  ad.show(activity)
}

Java

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  AppOpenAd ad = AppOpenAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "App open ad is not available.");
    return;
  }

  Log.d(TAG, "App open ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new AppOpenAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "App open ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(activity);
}

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

האזנה לאירועי מודעות

לפני שמציגים את המודעה, מאזינים לאירועי מודעות. בדוגמה הבאה רשומות קריאות חוזרות (callback) לאירועי מודעות:

Kotlin

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = appOpenAd
  if (ad == null) {
    Log.e(TAG, "App open ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : AppOpenAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // App open ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // App open ad did dismiss.
        appOpenAd = null
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // App open ad failed to show.
        Log.e(TAG, "App open ad failed to show: ${fullScreenContentError.message}")
      }

      override fun onAdImpression() {
        // App open ad did record an impression.
      }

      override fun onAdClicked() {
        // App open ad did record a click.
      }
    }
}

Java

private void listenToAdEvents() {
  // Listen for ad events.
  if (appOpenAd == null) {
    Log.e(TAG, "App open ad is not ready yet.");
    return;
  }

  appOpenAd.setAdEventCallback(
      new AppOpenAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // App open ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // App open ad did dismiss.
          appOpenAd = null;
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          // App open ad failed to show.
          Log.e(TAG, "App open ad failed to show: " + fullScreenContentError.getMessage());
        }

        @Override
        public void onAdImpression() {
          // App open ad did record an impression.
        }

        @Override
        public void onAdClicked() {
          // App open ad did record a click.
        }
      });
}

אופציונלי: האזנה לאירועי טעינה מראש

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

בדוגמה הבאה אפשר לראות איך נרשמים לאירועים של טעינה מראש של מודעות:

Kotlin

val preloadCallback =
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(TAG, "App open preload ad $preloadId failed to load with error: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "App open preload ad $preloadId is not available")
    }

    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
      Log.i(TAG, "App open preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
AppOpenAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

Java

PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "App open preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        Log.i(TAG, String.format("App open preload ad %s is not available", preloadId));
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, String.format("App open preload ad %s is available", preloadId));
      }
    };
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
AppOpenAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

אם מודעה לא נטענת, GMA Next-Gen SDK טוען מראש מודעות באופן אוטומטי ומנסה שוב לשלוח בקשות שנכשלו להגדרות שנטענו מראש. אל תפעילו בקשות טעינה ידניות בקריאות חוזרות (callback) של כשלים. בשיטות קריאה חוזרת של אירועי טעינה מראש, אל תקראו לשיטות pollAd,‏ destroy או start. קריאה לשיטות האלה בקריאות חוזרות (callbacks) יכולה להפעיל לולאות טעינה רקורסיביות.

אופציונלי: בדיקה אם יש מודעה זמינה

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

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return AppOpenAdPreloader.isAdAvailable(adUnitId)
}

Java

private boolean isAdAvailable(String adUnitId) {
  return AppOpenAdPreloader.isAdAvailable(adUnitId);
}

אופציונלי: הגדרת גודל המאגר הזמני

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

בדוגמה הבאה מוסבר איך להגדיר שטח אחסון זמני:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
AppOpenAdPreloader.start(adUnitId, preloadConfig)

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
AppOpenAdPreloader.start(adUnitId, preloadConfig);

מגבלות על טעינה מראש למטמון

‫GMA Next-Gen SDK אוכף מגבלה ברמת האפליקציה על המספר הכולל של מודעות שנטענות מראש בכל יחידות המודעות ומזהי הטעינה מראש:

  • מגבלת ברירת המחדל: Google שומרת בזיכרון עד שש מודעות שנטענו מראש. המגבלה הזו משותפת לכל הפורמטים ולכל המזהים של הטעינה מראש.
  • מומלץ להגדיר שטח אחסון זמני של שניים לכל מזהה טעינה מראש.

אופציונלי: הפסקת הטעינה מראש של מודעות

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

בדוגמה הבאה אפשר לראות איך להפסיק את הטעינה מראש של מודעות:

Kotlin

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  AppOpenAdPreloader.destroy(adUnitId)
}

Java

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  AppOpenAdPreloader.destroy(adUnitId);
}

אופציונלי: קוראים את פרטי התשובה.

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

בדוגמה הבאה אפשר לראות איך לקרוא את המידע על התגובה הבאה של המודעה שנטענה מראש:

Kotlin

val responseInfo = AppOpenAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

Java

ResponseInfo responseInfo = AppOpenAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());

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

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

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

המלצות

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

  • אל תציגו מודעה בפתיחת האפליקציה בפעם הראשונה שהמשתמש פותח אותה.
  • אם מסך הטעינה מסיים את הטעינה בזמן שהמודעה מוצגת, צריך לסגור את מסך הטעינה בשיטת הקריאה החוזרת (callback) של סגירת המודעה.
  • התוקף של מודעות בפתיחת האפליקציה פג ארבע שעות אחרי הטעינה. אל תציגו מודעה בפתיחת האפליקציה שנטענה לפני יותר מ-4 שעות.