Configurare gli annunci interstitial con premio

Seleziona la piattaforma: Android iOS Unity Flutter Android (legacy)

Gli annunci interstitial con premio sono un formato che ti consente di offrire premi per gli annunci che vengono visualizzati automaticamente durante le normali transizioni dell'app. A differenza degli annunci con premio, gli utenti non devono attivare la visualizzazione di un annuncio interstitial con premio. Per saperne di più, consulta le indicazioni sugli annunci interstitial con premio.

Questa guida spiega come integrare gli annunci interstitial con premio in un'app per Android.

Prima di iniziare

Prima di continuare, completa queste operazioni:

  • Configura GMA Next-Gen SDK.
  • Utilizza l'ID unità pubblicitaria interstitial con premio di prova ca-app-pub-3940256099942544/5354046379.
    • Quando crei e testi la tua app, assicurati di utilizzare annunci di prova anziché annunci di produzione live. Se non utilizzi l'ID unità pubblicitaria di test, Google può sospendere il tuo account.
    • Prima di pubblicare l'app, sostituisci questo ID con l'ID unità pubblicitaria.
    • Per informazioni dettagliate sugli annunci di prova GMA Next-Gen SDK, consulta Attivare gli annunci di prova.

Informazioni sul precaricamento degli annunci (beta)

Il precaricamento degli annunci (beta) in GMA Next-Gen SDK automatizza il caricamento e la memorizzazione nella cache degli annunci.

Il precaricamento degli annunci offre i seguenti vantaggi:

  • Gestione dei riferimenti: mantiene i riferimenti fino alla visualizzazione degli annunci.
  • Ricaricamento automatico: carica un nuovo annuncio quando ne viene recuperato uno dalla cache.
  • Nuovi tentativi gestiti: carica un nuovo annuncio quando il caricamento di uno non va a buon fine.
  • Gestione della scadenza: aggiorna gli annunci prima della scadenza.
  • Ottimizzazione della cache: ottimizza l'ordine della cache per pubblicare l'annuncio con la priorità più alta.
Nota: per caricare gli annunci manualmente, consulta Caricare un singolo annuncio interstitial con premio.

Avvia il precaricamento degli annunci

Per iniziare a precaricare gli annunci, chiama il metodo startPreload() una volta all'avvio dell'app. Dopo aver chiamato il metodo startPreload(), GMA Next-Gen SDK precarica automaticamente gli annunci e riprova le richieste non riuscite per le configurazioni precaricate.

L'esempio seguente mostra come iniziare il precaricamento degli annunci:

Kotlin

private fun startPreloading(adUnitId: String) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void startPreloading(String adUnitId) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);
}

Sostituisci AD_UNIT_ID con l'ID unità pubblicitaria.

L'esempio precedente mostra come utilizzare l'ID unità pubblicitaria come ID precaricamento. Un ID precaricamento è una stringa identificatore creata per identificare una configurazione di precaricamento degli annunci. Se la tua app richiede più configurazioni di targeting per lo stesso ID unità pubblicitaria, trasmetti un identificatore stringa personalizzato.

Recupera e mostra l'annuncio precaricato

Quando vuoi mostrare un annuncio, chiama il metodo pollAd(). GMA Next-Gen SDK recupera un annuncio disponibile e precarica automaticamente l'annuncio successivo in background. Se non è disponibile alcun annuncio, GMA Next-Gen SDK non restituisce annunci.

Quando hai un oggetto annuncio disponibile, chiama il metodo show per visualizzare l'annuncio. Utilizza un listener di premi per gestire gli eventi premio. Il seguente esempio mostra come recuperare e mostrare 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 = RewardedInterstitialAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded interstitial ad recorded an impression.")
      }
    }
  ad.show(activity) { rewardItem -> Log.d(TAG, "User earned reward: ${rewardItem.amount}") }
}

Java

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  final RewardedInterstitialAd ad = RewardedInterstitialAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.");
    return;
  }

  Log.d(TAG, "Rewarded interstitial ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Rewarded interstitial ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(
      activity,
      rewardItem -> {
        Log.d(TAG, "User earned reward: " + rewardItem.getAmount());
      });
}

Finché non sei pronto a mostrare un annuncio, evita di chiamare il metodo pollAd(). Per leggere le informazioni sulla risposta all'annuncio senza mostrarle, vedi Leggere le informazioni sulla risposta.

Ascoltare gli eventi degli annunci

Prima di mostrare l'annuncio, ascolta gli eventi dell'annuncio. L'esempio seguente registra i callback per gli eventi annuncio:

Kotlin

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = rewardedInterstitialAd
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // Rewarded interstitial ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // Rewarded interstitial ad did dismiss.
        rewardedInterstitialAd = null
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // Rewarded interstitial ad failed to show.
        Log.e(TAG, "Rewarded interstitial ad failed to show: ${fullScreenContentError.message}")
      }

      override fun onAdImpression() {
        // Rewarded interstitial ad did record an impression.
      }

      override fun onAdClicked() {
        // Rewarded interstitial ad did record a click.
      }
    }
}

Java

private void listenToAdEvents() {
  // Listen for ad events.
  if (rewardedInterstitialAd == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.");
    return;
  }

  rewardedInterstitialAd.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded interstitial ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // Rewarded interstitial ad did dismiss.
          rewardedInterstitialAd = null;
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          // Rewarded interstitial ad failed to show.
          Log.e(
              TAG,
              "Rewarded interstitial ad failed to show: " + fullScreenContentError.getMessage());
        }

        @Override
        public void onAdImpression() {
          // Rewarded interstitial ad did record an impression.
        }

        @Override
        public void onAdClicked() {
          // Rewarded interstitial ad did record a click.
        }
      });
}

(Facoltativo) Convalida i callback di verifica lato server (SSV)

Se la tua app richiede dati aggiuntivi nei callback di verifica lato server, utilizza la funzionalità dei dati personalizzati degli annunci. I server pubblicitari di Google trasmettono qualsiasi valore stringa impostato su un oggetto annuncio al parametro di query custom_data del callback SSV. Se non è impostato alcun valore di dati personalizzati, il valore parametro di query custom_data non è presente nel callback SSV.

L'esempio seguente imposta dati personalizzati su un oggetto annuncio prima di mostrare l'annuncio:

Kotlin

RewardedInterstitialAd.load(
  context,
  AD_UNIT_ID,
  AdRequest.Builder().build(),
  object : RewardedInterstitialAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedInterstitialAd) {
      rewardedInterstitialAd = ad
      val options =
        ServerSideVerificationOptions.Builder().setCustomData("SAMPLE_CUSTOM_DATA_STRING").build()
      rewardedInterstitialAd?.setServerSideVerificationOptions(options)
    }
  },
)

Java

RewardedInterstitialAd.load(
    context,
    AD_UNIT_ID,
    new AdRequest.Builder().build(),
    new RewardedInterstitialAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedInterstitialAd ad) {
        rewardedInterstitialAd = ad;
        ServerSideVerificationOptions options =
            new ServerSideVerificationOptions.Builder()
                .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
                .build();
        rewardedInterstitialAd.setServerSideVerificationOptions(options);
      }
    });

Sostituisci SAMPLE_CUSTOM_DATA_STRING con i tuoi dati personalizzati.

(Facoltativo) Ascoltare gli eventi di precaricamento

Quando inizi a precaricare gli annunci, registrati per gli eventi di precaricamento per ricevere una notifica quando gli annunci vengono precaricati correttamente, non vengono precaricati o la cache degli annunci è esaurita.

L'esempio seguente mostra come registrarsi per il precaricamento degli eventi annuncio:

Kotlin

val preloadCallback =
  // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(
        TAG,
        "Rewarded interstitial preload ad $preloadId failed to load with error: ${adError.message}",
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded 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, "Rewarded interstitial preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

Java

PreloadCallback preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded 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(@NonNull String preloadId) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is not available");
        // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is available");
      }
    };
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

Quando un annuncio non viene caricato, GMA Next-Gen SDK precarica automaticamente gli annunci e riprova le richieste non riuscite per le configurazioni precaricate.

(Facoltativo) Controlla la disponibilità degli annunci

Se devi sapere se un annuncio è disponibile, controlla la disponibilità dell'annuncio. L'esempio seguente verifica se è disponibile un annuncio precaricato:

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return RewardedInterstitialAdPreloader.isAdAvailable(adUnitId)
}

Java

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

(Facoltativo) Imposta la dimensione del buffer

La dimensione del buffer controlla il numero di annunci precaricati memorizzati. Per impostazione predefinita, Google ottimizza le dimensioni del buffer per bilanciare il consumo di memoria e la latenza della pubblicazione di annunci. Puoi impostare una dimensione del buffer personalizzata per aumentare il numero di annunci conservati in memoria. Ti consigliamo una dimensione del buffer di due annunci precaricati.

Il seguente esempio mostra come impostare una dimensione del buffer:

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);
}

Limiti della cache precaricata

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

  • Limite predefinito: Google memorizza un massimo di sei annunci precaricati. Questo limite è condiviso tra tutti i formati e gli ID precaricamento.
  • Ti consigliamo di mantenere una dimensione del buffer di due per ogni ID precaricamento.

(Facoltativo) Interrompi il precaricamento degli annunci

Se non devi mostrare di nuovo gli annunci per un ID precaricamento specifico nella sessione, puoi interrompere il precaricamento degli annunci. Per interrompere il caricamento degli annunci per un ID precaricamento specifico, chiama il metodo destroy() con un ID precaricamento. La chiamata al metodo destroy() rimuove dalla cache tutti gli annunci precaricati associati all'ID precaricamento.

L'esempio seguente mostra come interrompere il precaricamento degli annunci:

Kotlin

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  RewardedInterstitialAdPreloader.destroy(adUnitId)
}

Java

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  RewardedInterstitialAdPreloader.destroy(adUnitId);
}

(Facoltativo) Leggi le informazioni sulla risposta

Leggi le informazioni sulla risposta del successivo annuncio precaricato senza rimuoverlo dalla cache.

Il seguente esempio mostra come leggere le informazioni sulla risposta all'annuncio precaricato successivo:

Kotlin

val responseInfo = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

Java

ResponseInfo responseInfo = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());