Przejście na wstępne ładowanie reklam

Wstępne ładowanie reklam automatyzuje wczytywanie, buforowanie i ponowne wczytywanie reklam w GMA Next-Gen SDK. Jeśli używasz pojedynczego ładowania, przejdź na wstępne ładowanie reklam, aby korzystać z automatycznego zarządzania cyklem życia, zarządzanych ponownych prób i zoptymalizowanego wyboru reklam. Szczegółowe informacje o wstępnym ładowaniu reklam znajdziesz w artykule Wstępne ładowanie reklam. Wstępne ładowanie reklam obsługuje formaty reklam wyświetlanych przy otwarciu aplikacji, reklam pełnoekranowych, reklam z nagrodą i reklam pełnoekranowych z nagrodą.

Na tej stronie dowiesz się, jak przenieść dotychczasową implementację pojedynczego ładowania reklam na wstępne ładowanie reklam. W tym przewodniku jako przykład używamy reklam pełnoekranowych, ale ten sam proces możesz zastosować do obsługiwanych formatów reklam.

Wymagania wstępne

Zanim przejdziesz dalej, wykonaj te czynności:

Żądanie reklam z wstępnym ładowaniem reklam

W przypadku pojedynczego ładowania wysyłasz pojedyncze żądanie reklamy. W przypadku wstępnego ładowania reklam uruchamiasz wstępne ładowanie tylko raz za pomocą identyfikatora wstępnego ładowania i konfiguracji wstępnego ładowania.

W przykładach poniżej porównujemy żądania reklam z pojedynczym ładowaniem i wstępnym ładowaniem reklam:

Kotlin

Pojedyncze ładowanie:

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

Wstępne ładowanie reklam:

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

Java

Pojedyncze ładowanie:

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

Wstępne ładowanie reklam:

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

Przełączanie na wywołania zwrotne wstępnego ładowania

W przypadku pojedynczego ładowania do każdego żądania reklamy dołączasz wywołanie zwrotne ładowania. W przypadku wstępnego ładowania reklam rejestrujesz detektor wywołań zwrotnych, aby obserwować aktualizacje pamięci podręcznej wstępnego ładowania. Te wywołania zwrotne powiadamiają aplikację, gdy reklamy zostaną wstępnie załadowane, nie uda się ich załadować lub gdy pamięć podręczna zostanie wyczerpana.

W przykładach poniżej porównujemy sposób rejestrowania wywołań zwrotnych wstępnego ładowania w przypadku pojedynczego ładowania i wstępnego ładowania reklam:

Kotlin

Pojedyncze ładowanie:

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

Wstępne ładowanie reklam:

// 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

Pojedyncze ładowanie:

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

Wstępne ładowanie reklam:

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

Wstępne ładowanie wywołuje metody wywołań zwrotnych, gdy GMA Next-Gen SDK wczytuje lub buforuje reklamę albo gdy aplikacja wyświetla reklamę.

Wyświetlanie reklam z pamięci podręcznej

W przypadku pojedynczego ładowania zapisujesz załadowaną reklamę w zmiennej i wyświetlasz ją, gdy jest dostępna. W przypadku wstępnego ładowania reklam, gdy reklama jest gotowa do wyświetlenia, pobierasz ją bezpośrednio z pamięci podręcznej. W obu przypadkach przed wyświetleniem reklamy dołącz do niej detektor zdarzeń.

W przykładach poniżej porównujemy wyświetlanie reklamy z wstępnym ładowaniem reklam i pojedynczym ładowaniem:

Kotlin

Pojedyncze ładowanie:

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

Wstępne ładowanie reklam:

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

Java

Pojedyncze ładowanie:

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

Wstępne ładowanie reklam:

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

Usuwanie ręcznego buforowania i ponownego ładowania

Gdy otrzymasz reklamę, wstępne ładowanie automatycznie załaduje reklamę zastępczą. W przeciwieństwie do pojedynczego ładowania nie musisz ręcznie przechowywać odwołań do reklam ani pisać logiki ponownego ładowania.

Usuń z kodu te wzorce:

  • Buforowanie zmiennych składowych: usuń zmienne składowe, które przechowują obiekty reklam.
  • Ręczne ponowne ładowanie: usuń wywołania ładowania po zamknięciu reklamy przez użytkownika lub gdy nie uda się jej wyświetlić.
  • Niestandardowe minutniki ponawiania: usuń moduły obsługi ponawiania, pętle wycofywania i minutniki. GMA Next-Gen SDK automatycznie ponawia nieudane żądania wstępnego ładowania.

Porównywanie kompletnych przykładów

W przykładach poniżej porównujemy kompletną implementację reklamy pełnoekranowej przed i po przejściu na wstępne ładowanie reklam:

Kotlin

Pojedyncze ładowanie:

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

Wstępne ładowanie reklam:

// 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

Pojedyncze ładowanie:

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

Wstępne ładowanie reklam:

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

Dalsze kroki

Zapoznaj się z tymi materiałami, aby skonfigurować funkcje wstępnego ładowania, zintegrować formaty reklam i przetestować implementację: