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

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

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

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

• ניהול הפניות: מחזיק מודעות שנטענו כדי שלא תצטרכו לשמור הפניות עד שתהיו מוכנים להציג אותן.
• טעינה אוטומטית מחדש: המערכת טוענת מודעה חדשה באופן אוטומטי כשמוציאים מודעה מהמטמון.
• ניסיונות חוזרים מנוהלים: ניסיונות חוזרים אוטומטיים של בקשות שנכשלו באמצעות השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
• טיפול בתפוגה: רענון אוטומטי של המודעות לפני שהתוקף שלהן פג (בדרך כלל אחרי שעה).
• אופטימיזציה של מטמון: אם משתמשים בגודל מטמון גדול מ-1, 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)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}
InterstitialAdSnippets.kt

Java

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

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

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

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

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

Kotlin

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = InterstitialAdPreloader.pollAd(adUnitId)

  // Interact with the ad object as needed.
  ad?.apply {
    Log.d(TAG, "Interstitial ad response info: ${this.getResponseInfo()}")
    this.adEventCallback =
      object : InterstitialAdEventCallback {
        override fun onAdImpression() {
          Log.d(TAG, "Interstitial ad recorded an impression.")
        }

        override fun onAdPaid(value: AdValue) {
          Log.d(TAG, "Interstitial ad onPaidEvent: ${value.valueMicros} ${value.currencyCode}")
        }
      }

    // Show the ad.
    ad.show(activity)
  }
}
InterstitialAdSnippets.kt

Java

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

  // Interact with the ad object as needed.
  if (ad != null) {
    Log.d(TAG, "Interstitial ad response info: " + ad.getResponseInfo());
    ad.setAdEventCallback(
        new InterstitialAdEventCallback() {
          @Override
          public void onAdImpression() {
            Log.d(TAG, "Interstitial ad recorded an impression.");
          }

          @Override
          public void onAdPaid(AdValue value) {
            Log.d(
                TAG,
                "Interstitial ad onPaidEvent: "
                    + value.getValueMicros()
                    + " "
                    + value.getCurrencyCode());
          }
        });

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

אחזור מטא-נתונים של מודעות שנטענו מראש

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

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

Kotlin

private fun peekAdResponseInfo(preloadId: String) {
  InterstitialAdPreloader.peekAdResponseInfo(preloadId)?.let {
    Log.d(TAG, "Peeked ad response ID: ${it.responseId}")
  }
}
InterstitialAdSnippets.kt

Java

private void peekAdResponseInfo(String preloadId) {
  ResponseInfo responseInfo = InterstitialAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo != null) {
    Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());
  }
}
InterstitialAdSnippets.java

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

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

• קבלת נתוני זמינות של מודעות לטעינה מראש
• האזנה לזמינות של מודעות טרום-טעינה

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

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

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return InterstitialAdPreloader.isAdAvailable(adUnitId)
}
InterstitialAdSnippets.kt

Java

private boolean isAdAvailable(String adUnitId) {
  return InterstitialAdPreloader.isAdAvailable(adUnitId);
}
InterstitialAdSnippets.java

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

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

אירועי טעינה מראש מיועדים למטרות ניתוח נתונים. בתוך קריאות חוזרות (callback) של אירוע טעינה מראש:

• אין צורך להתקשר אל startPreload.
• מומלץ להימנע מהפעלת הפונקציה pollAd אלא אם המודעה תוצג באופן מיידי.

בדוגמה הבאה מתבצעת הרשמה לאירועים שקשורים למודעות:

Kotlin

private fun startPreloadingWithCallback(adUnitId: String) {
  val preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    object : PreloadCallback {
      override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
        Log.i(
          TAG,
          ("Interstitial preload ad $preloadId failed to load with error: ${adError.message}"),
        )
        // [Optional] Get the error response info for additional details.
        // val responseInfo = adError.responseInfo
      }

      override fun onAdsExhausted(preloadId: String) {
        Log.i(TAG, "Interstitial preload ad $preloadId is not available")
        // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
      }

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

Java

private void startPreloadingWithCallback(String adUnitId) {
  PreloadCallback preloadCallback =
      // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
      new PreloadCallback() {
        @Override
        public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
          Log.e(
              TAG,
              String.format(
                  "Interstitial preload ad %s failed to load with error: %s",
                  preloadId, adError.getMessage()));
          // [Optional] Get the error response info for additional details.
          // ResponseInfo responseInfo = adError.getResponseInfo();
        }

        @Override
        public void onAdsExhausted(String preloadId) {
          Log.i(TAG, "Interstitial preload ad " + preloadId + " is not available");
          // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
        }

        @Override
        public void onAdPreloaded(String preloadId, ResponseInfo responseInfo) {
          Log.i(TAG, "Interstitial preload ad " + preloadId + " is available");
        }
      };

  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);
}
InterstitialAdSnippets.java

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

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

הגדרת גודל המאגר

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

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 3)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}
InterstitialAdSnippets.kt

Java

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 3);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}
InterstitialAdSnippets.java

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

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

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

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