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

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

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

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

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

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

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

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

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

Kotlin

שימוש אחד:

// Request a single ad.
val adRequest = AdRequest.Builder(adUnitId).build()
InterstitialAd.load(adRequest, adLoadCallback)

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

// Start the preloader once with a preload configuration.
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
InterstitialAdPreloader.start(adUnitId, preloadConfig)

Java

שימוש אחד:

// Request a single ad.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
InterstitialAd.load(adRequest, adLoadCallback);

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

// Start the preloader once with a preload configuration.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
InterstitialAdPreloader.start(adUnitId, preloadConfig);

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

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

בדוגמאות הבאות אפשר לראות איך רושמים קריאות חוזרות (callbacks) לטעינה מראש של מודעה אחת ושל כמה מודעות:

Kotlin

שימוש אחד:

// Listen for single ad request load results.
val adLoadCallback =
  object : AdLoadCallback<InterstitialAd> {
    override fun onAdLoaded(ad: InterstitialAd) {
      // Ad loaded for a single request.
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {
      Log.d(TAG, "Ad failed to load: ${adError.message}")
    }
  }

InterstitialAd.load(adRequest, adLoadCallback)

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

// Observe cache updates across multiple ads.
val preloadCallback =
  object : PreloadCallback {
    override fun onAdPreloaded(
      preloadId: String,
      responseInfo: ResponseInfo,
    ) {
      // Ad preloaded into the cache and is ready to show.
    }

    override fun onAdFailedToPreload(
      preloadId: String,
      adError: LoadAdError,
    ) {
      Log.d(TAG, "Ad failed to preload: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      // All preloaded ads in the cache have been shown.
      Log.d(TAG, "Ads exhausted for: $preloadId")
    }
  }

InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

Java

שימוש אחד:

// Listen for single ad request load results.
AdLoadCallback<InterstitialAd> adLoadCallback =
    new AdLoadCallback<InterstitialAd>() {
      @Override
      public void onAdLoaded(@NonNull InterstitialAd ad) {
        // Ad loaded for a single request.
      }

      @Override
      public void onAdFailedToLoad(@NonNull LoadAdError adError) {
        Log.d(TAG, "Ad failed to load: " + adError.getMessage());
      }
    };

InterstitialAd.load(adRequest, adLoadCallback);

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

// Observe cache updates across multiple ads.
PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdPreloaded(
          @NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        // Ad preloaded into the cache and is ready to show.
      }

      @Override
      public void onAdFailedToPreload(
          @NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(TAG, "Ad failed to preload: " + adError.getMessage());
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        // All preloaded ads in the cache have been shown.
        Log.d(TAG, "Ads exhausted for: " + preloadId);
      }
    };

InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

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

הצגת מודעות מהמטמון

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

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

Kotlin

שימוש אחד:

// Retrieve the ad from a saved variable.
val interstitialAd = this.interstitialAd ?: return
// Display the ad.
interstitialAd.show(activity)

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

// Retrieve the ad directly from the preloader cache.
val interstitialAd = InterstitialAdPreloader.pollAd(adUnitId) ?: return
// Display the ad.
interstitialAd.show(activity)

Java

שימוש אחד:

// Retrieve the ad from a saved variable.
InterstitialAd interstitialAd = this.interstitialAd;
if (interstitialAd == null) {
  return;
}
// Display the ad.
interstitialAd.show(activity);

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

// Retrieve the ad directly from the preloader cache.
InterstitialAd interstitialAd = InterstitialAdPreloader.pollAd(adUnitId);
if (interstitialAd == null) {
  return;
}
// Display the ad.
interstitialAd.show(activity);

הסרת השמירה הידנית במטמון והטעינה מחדש

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

צריך להסיר את התבניות הבאות מהקוד:

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

השוואה בין דוגמאות פתורות

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

Kotlin

שימוש אחד:

// 1. Maintain a member variable to store the ad.
private var interstitialAd: InterstitialAd? = null

// 2. Load the ad and listen for load completion.
private fun loadAd() {
  val adRequest = AdRequest.Builder(adUnitId).build()
  InterstitialAd.load(
    adRequest,
    object : AdLoadCallback<InterstitialAd> {
      override fun onAdLoaded(ad: InterstitialAd) {
        interstitialAd = ad
      }

      override fun onAdFailedToLoad(adError: LoadAdError) {
        interstitialAd = null
      }
    },
  )
}

// 3. Show the saved ad.
private fun showAd(activity: Activity) {
  val interstitialAd = this.interstitialAd ?: return
  interstitialAd.adEventCallback =
    object : InterstitialAdEventCallback {
      override fun onAdDismissedFullScreenContent() {
        // Reload the ad after dismissal in single-load integrations.
        loadAd()
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError,
      ) {
        Log.d(TAG, "Ad failed to show: ${fullScreenContentError.message}")
      }
    }
  interstitialAd.show(activity)
}

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

// 1. Start preloading with a callback to listen for loaded ads.
private fun startPreloading(adUnitId: String) {
  val preloadCallback =
    object : PreloadCallback {
      override fun onAdPreloaded(
        preloadId: String,
        responseInfo: ResponseInfo,
      ) {
        // Ad preloaded successfully.
      }

      override fun onAdFailedToPreload(
        preloadId: String,
        adError: LoadAdError,
      ) {
        Log.d(TAG, "Ad failed to preload: ${adError.message}")
      }
    }

  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)
}

// 2. Show the ad immediately after polling.
private fun showAd(activity: Activity, adUnitId: String) {
  val interstitialAd = InterstitialAdPreloader.pollAd(adUnitId) ?: return
  interstitialAd.adEventCallback =
    object : InterstitialAdEventCallback {
      override fun onAdDismissedFullScreenContent() {
        // Preloading automatically fetches a replacement ad.
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError,
      ) {
        Log.d(TAG, "Ad failed to show: ${fullScreenContentError.message}")
      }
    }
  interstitialAd.show(activity)
}

Java

שימוש אחד:

// 1. Maintain a member variable to store the ad.
private InterstitialAd interstitialAd;

// 2. Load the ad and listen for load completion.
private void loadAd() {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  InterstitialAd.load(
      adRequest,
      new AdLoadCallback<InterstitialAd>() {
        @Override
        public void onAdLoaded(@NonNull InterstitialAd ad) {
          interstitialAd = ad;
        }

        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError adError) {
          interstitialAd = null;
        }
      });
}

// 3. Show the saved ad.
private void showAd(Activity activity) {
  if (interstitialAd == null) {
    return;
  }
  interstitialAd.setAdEventCallback(
      new InterstitialAdEventCallback() {
        @Override
        public void onAdDismissedFullScreenContent() {
          // Reload the ad after dismissal in single-load integrations.
          loadAd();
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          Log.d(
              TAG,
              "Ad failed to show: " + fullScreenContentError.getMessage());
        }
      });
  interstitialAd.show(activity);
}

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

// 1. Start preloading with a callback to listen for loaded ads.
private void startPreloading(String adUnitId) {
  PreloadCallback preloadCallback =
      new PreloadCallback() {
        @Override
        public void onAdPreloaded(
            @NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
          // Ad preloaded successfully.
        }

        @Override
        public void onAdFailedToPreload(
            @NonNull String preloadId, @NonNull LoadAdError adError) {
          Log.d(TAG, "Ad failed to preload: " + adError.getMessage());
        }
      };

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

// 2. Show the ad immediately after polling.
private void showAd(Activity activity, String adUnitId) {
  InterstitialAd interstitialAd = InterstitialAdPreloader.pollAd(adUnitId);
  if (interstitialAd == null) {
    return;
  }
  interstitialAd.setAdEventCallback(
      new InterstitialAdEventCallback() {
        @Override
        public void onAdDismissedFullScreenContent() {
          // Preloading automatically fetches a replacement ad.
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          Log.d(
              TAG,
              "Ad failed to show: " + fullScreenContentError.getMessage());
        }
      });
  interstitialAd.show(activity);
}

השלבים הבאים

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

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