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

SDK.

בחירת פלטפורמה: Android iOS Unity Flutter Android (Legacy)

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

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

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

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

לפני שממשיכים, צריך:

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

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

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

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

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

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

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

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

Kotlin

private fun startPreloading(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  AppOpenAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void startPreloading(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  AppOpenAdPreloader.start(adUnitId, preloadConfig);
}

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

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

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

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

כשיש אובייקט מודעה זמין, קוראים לשיטה 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);
}

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

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

לפני הצגת המודעה, צריך להמתין לאירועים שקשורים למודעה. בדוגמה הבאה אפשר לראות איך רושמים קריאות חוזרות (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

private fun startPreloadingWithCallback(adUnitId: String) {
  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

private void startPreloadingWithCallback(String adUnitId) {
  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 טוען מראש מודעות באופן אוטומטי ומנסה שוב בקשות שנכשלו להגדרות שנטענו מראש.

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

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

Kotlin

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

Java

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

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

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

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

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Four is the recommended maximum buffer size.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 4)
  AppOpenAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  // Four is the recommended maximum buffer size.
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 4);
  AppOpenAdPreloader.start(adUnitId, preloadConfig);
}

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

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

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

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

אם אתם לא רוצים להציג שוב מודעות עם מזהה טעינה מראש ספציפי בסשן, אתם יכולים להפסיק את הטעינה מראש של המודעות. כדי להפסיק לטעון מודעות למזהה טעינה מראש ספציפי, צריך להתקשר לשיטת destroy() עם מזהה טעינה מראש. הפעלת השיטה 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);
}

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

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

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

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) מתרחשת כשהאפליקציה מופעלת מאפס, למשל כשמשתמש פותח את האפליקציה בפעם הראשונה או אחרי סגירה של האפליקציה בגלל חוסר זיכרון. במהלך הפעלה במצב התחלתי (cold start), אין לכם מודעה בפתיחת האפליקציה שנטענה בעבר ומוכנה להצגה באופן מיידי.

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

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

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

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

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