Precaricamento degli annunci (beta)

Seleziona la piattaforma: Android iOS Unity Android (legacy)

Il precaricamento degli annunci è una funzionalità di caricamento degli annunci gestita da Google in GMA Next-Gen SDK che gestisce il caricamento e la memorizzazione nella cache degli annunci per tuo conto. Il precaricamento degli annunci richiede una modifica del modo in cui gestisci il caricamento degli annunci. Per ottimizzare le prestazioni utilizzando il precaricamento degli annunci, disattiva la memorizzazione nella cache personalizzata e delega questa responsabilità a GMA Next-Gen SDK.

Il precaricamento degli annunci offre i seguenti vantaggi rispetto al caricamento manuale degli annunci:

• Gestione dei riferimenti:conserva gli annunci caricati in modo che tu non debba mantenere i riferimenti finché non sono pronti per essere mostrati.
• Ricarica automatica:carica automaticamente un nuovo annuncio quando ne estrai uno dalla cache.
• Riprova gestita:riprova automaticamente le richieste non riuscite utilizzando il backoff esponenziale.
• Gestione della scadenza:aggiorna automaticamente gli annunci prima che scadano (in genere dopo un'ora).
• Ottimizzazione della cache: se utilizzi una dimensione della cache maggiore di uno, GMA Next-Gen SDK ottimizza l'ordine della cache per pubblicare l'annuncio migliore.

Questa guida illustra come configurare gli annunci di precaricamento, controllare la disponibilità degli annunci di precaricamento e mostrare l'annuncio precaricato.

Prerequisiti

Prima di procedere con questo tutorial, devi configurare GMA Next-Gen SDK.

Inizia il precaricamento degli annunci

Quando l'app si avvia, chiama il metodo startPreload una volta. Dopo aver chiamato il metodo startPreload, GMA Next-Gen SDK precarica automaticamente gli annunci e riprova le richieste non riuscite per le configurazioni precaricate.

Il seguente esempio avvia il precaricamento degli annunci:

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

Recupera e mostra l'annuncio precaricato

Quando utilizzi il precaricamento degli annunci, GMA Next-Gen SDK conserva gli annunci memorizzati nella cache. Quando vuoi mostrare un annuncio, chiama pollAd. GMA Next-Gen SDK recupera l'annuncio disponibile e precarica automaticamente l'annuncio successivo in background.

Evita di chiamare il metodo pollAd finché non è tutto pronto per mostrare un annuncio. Mantenere gli annunci nella cache consente a GMA Next-Gen SDK di aggiornare automaticamente gli annunci scaduti ed eseguire l'ottimizzazione della cache.

Il seguente esempio recupera e mostra un annuncio precaricato:

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

Recupera i metadati dell'annuncio precaricato

Per recuperare i metadati dell'annuncio precaricato, puoi cercare l'oggetto delle informazioni sulla risposta dell'annuncio. Questa procedura ti consente di esaminare i metadati dell'annuncio senza rimuoverlo dalla cache.

Il seguente esempio cerca i metadati di un annuncio precaricato dall'oggetto delle informazioni sulla risposta:

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

Controlla la disponibilità degli annunci di precaricamento

Per verificare la disponibilità degli annunci, scegli una delle seguenti opzioni:

• Recupera la disponibilità degli annunci di precaricamento
• Ascolta la disponibilità degli annunci di precaricamento

Recupera la disponibilità degli annunci precaricati

Il seguente esempio verifica la disponibilità degli annunci:

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

Ascolta la disponibilità degli annunci precaricati

Registra gli eventi di precaricamento per ricevere una notifica quando gli annunci vengono precaricati correttamente, non vengono precaricati o la cache degli annunci è esaurita.

Gli eventi di precaricamento sono destinati a scopi di analisi. All'interno dei callback degli eventi di precaricamento:

• Non chiamare startPreload.
• Evita di chiamare pollAd a meno che l'annuncio non venga mostrato immediatamente.

Il seguente esempio registra gli eventi degli annunci:

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

Interrompi il precaricamento degli annunci

Se non devi mostrare di nuovo gli annunci per un ID di precaricamento nella sessione, puoi interrompere il precaricamento degli annunci. Per interrompere il precaricamento degli annunci per un ID di precaricamento specifico, chiama destroy con un ID di precaricamento. Per interrompere il precaricamento per tutti i precaricatori, chiama destroyAll.

Imposta la dimensione del buffer

La dimensione del buffer controlla il numero di annunci precaricati mantenuti in memoria. Per impostazione predefinita, Google ottimizza la dimensione del buffer per bilanciare il consumo di memoria e la latenza della pubblicazione degli annunci. Se la tua app mostra gli annunci prima che venga caricato l'annuncio successivo, puoi impostare una dimensione del buffer personalizzata per aumentare il numero di annunci mantenuti in memoria.

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

Limiti della cache di precaricamento

GMA Next-Gen SDK applica un limite a livello di app al numero totale di annunci precaricati in tutte le unità pubblicitarie e gli ID di precaricamento:

• Limite predefinito: GMA Next-Gen SDK mantiene in memoria un massimo di 6 annunci precaricati. Questo limite è condiviso tra tutti i formati e gli ID di precaricamento.
• Ti consigliamo di mantenere una dimensione del buffer di 2 o 3 per ID di precaricamento.

Nota: se la tua app può trarre vantaggio da un aumento del limite a livello di app, contatta il tuo account manager per richiedere un aumento.