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

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

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

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

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

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

כדי להתחיל את הטעינה מראש, מתקשרים אל startPreload(). ‫Google Mobile Ads SDK מנסה באופן אוטומטי לשלוח שוב בקשות להצגת מודעות שנכשלו בהגדרות שנטענו מראש.

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

Kotlin

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

Java

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

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

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

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

כדי להפסיק את הטעינה מראש של מודעות, קוראים ל-destroy() עם מזהה טעינה מראש.

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

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

Kotlin

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

Java

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

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

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

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")
      }

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

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");
        }

        @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);
}

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

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

בדוגמה הבאה מוצגת מודעה שנטענה מראש:

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)
  }
}

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);
  }
}

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

כדי לדעת אם יש מודעות זמינות, צריך להתקשר אל isAdAvailable:

Kotlin

private fun isAdAvailable(adUnitID: String): Boolean {
  return InterstitialAdPreloader.isAdAvailable(adUnitID)
}

Java

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