Esegui la migrazione al precaricamento degli annunci

Il precaricamento degli annunci automatizza il caricamento, la memorizzazione nella cache e il ricaricamento degli annunci in GMA Next-Gen SDK. Se utilizzi il caricamento singolo, esegui la migrazione al precaricamento degli annunci per la gestione automatizzata del ciclo di vita, i tentativi gestiti e la selezione ottimizzata degli annunci. Per i dettagli concettuali sul precaricamento degli annunci, consulta Precaricamento degli annunci. Il precaricamento degli annunci supporta i formati degli annunci apertura app, interstitial, con premio e interstitial con premio.

Questa pagina ti guida nella migrazione di un'implementazione di annunci a caricamento singolo esistente al precaricamento degli annunci. Questa guida utilizza gli annunci interstitial come esempio, ma puoi applicare la stessa procedura ai formati degli annunci supportati.

Prerequisiti

Prima di continuare, completa i seguenti passaggi:

Richiedi annunci con il precaricamento degli annunci

Nel caricamento singolo, richiedi un singolo annuncio per ogni richiesta di annuncio. Con il precaricamento degli annunci, avvii il precaricatore una volta con l'ID di precaricamento e la configurazione di precaricamento.

I seguenti esempi confrontano le richieste di annunci con il caricamento singolo e il precaricamento degli annunci:

Kotlin

Caricamento singolo:

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

Precaricamento degli annunci:

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

Java

Caricamento singolo:

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

Precaricamento degli annunci:

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

Passa ai callback di precaricamento

Nel caricamento singolo, colleghi un callback di caricamento a ogni singola richiesta di annuncio. Con il precaricamento degli annunci, registri un listener di callback per osservare gli aggiornamenti della cache del precaricatore. Questi callback inviano una notifica alla tua app quando gli annunci terminano il precaricamento, non vengono caricati o esauriscono la cache.

I seguenti esempi confrontano come registrare i callback di precaricamento per il caricamento singolo e il precaricamento degli annunci:

Kotlin

Caricamento singolo:

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

Precaricamento degli annunci:

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

Caricamento singolo:

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

Precaricamento degli annunci:

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

Il precaricatore richiama i metodi di callback quando GMA Next-Gen SDK carica o memorizza nella cache un annuncio oppure quando la tua app mostra un annuncio.

Mostra gli annunci dalla cache

Nel caricamento singolo, salvi l'annuncio caricato in una variabile e lo mostri quando è disponibile. Con il precaricamento degli annunci, quando un annuncio è disponibile per la visualizzazione, lo recuperi direttamente dalla cache. In entrambi gli approcci, collega il listener di eventi all'annuncio prima di mostrarlo.

I seguenti esempi confrontano la visualizzazione di un annuncio con il precaricamento degli annunci rispetto al caricamento singolo:

Kotlin

Caricamento singolo:

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

Precaricamento degli annunci:

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

Java

Caricamento singolo:

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

Precaricamento degli annunci:

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

Rimuovi la memorizzazione nella cache e il ricaricamento manuali

Il precaricatore carica automaticamente un annuncio sostitutivo quando ricevi l'annuncio. A differenza del caricamento singolo, non devi archiviare manualmente i riferimenti agli annunci né scrivere la logica di ricaricamento.

Rimuovi i seguenti pattern dal codice:

  • Memorizzazione nella cache delle variabili membro: elimina le variabili membro che memorizzano gli oggetti annuncio.
  • Ricaricamenti manuali: elimina le chiamate di caricamento dopo che l'utente ha ignorato l'annuncio o non è riuscito a visualizzarlo.
  • Timer di nuovi tentativi personalizzati: elimina i gestori di nuovi tentativi, i loop di backoff e i timer. GMA Next-Gen SDK ritenta automaticamente le richieste di precaricamento non riuscite.

Confronta gli esempi completi

I seguenti esempi confrontano un'implementazione completa di annunci interstitial prima e dopo la migrazione al precaricamento degli annunci:

Kotlin

Caricamento singolo:

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

Precaricamento degli annunci:

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

Caricamento singolo:

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

Precaricamento degli annunci:

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

Passaggi successivi

Esplora le seguenti risorse per configurare le funzionalità di precaricamento, integrare i formati degli annunci e testare l'implementazione: