Configurare gli annunci con premio

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

Gli annunci con premio ti consentono di premiare con articoli in-app gli utenti che hanno interagito con gli annunci video, gli annunci demo e i sondaggi.

Questa guida spiega come integrare gli annunci 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 con premio di test ca-app-pub-3940256099942544/5224354917.
    • Quando crei e testi l'app, assicurati di utilizzare annunci di test anziché annunci live di produzione. 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 test GMA Next-Gen SDK, consulta Attivare gli annunci di test.

Informazioni sul precaricamento degli annunci (beta)

Il precaricamento degli annunci 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.
  • Ripetizioni gestite: carica un nuovo annuncio quando il caricamento di uno non riesce.
  • 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.

Avviare il precaricamento degli annunci

Per iniziare a precaricare gli annunci, chiama il metodo start una volta quando inizializzi GMA Next-Gen SDK. Dopo aver chiamato il start metodo, GMA Next-Gen SDK precarica automaticamente gli annunci e riprova a inviare le richieste non riuscite per le configurazioni precaricate.

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

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.start(adUnitId, preloadConfig);

Sostituisci AD_UNIT_ID con l'ID unità pubblicitaria.

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

Il precaricamento degli annunci non supporta la modifica dei parametri di targeting o delle richieste di annunci. Se devi modificare i parametri di targeting tra le richieste, utilizza il caricamento singolo.

Recuperare e mostrare l'annuncio precaricato

Prima di mostrare l'annuncio, chiama il metodo pollAd. Non memorizzare l'oggetto dell'annuncio precaricato. Quando chiami il pollAd metodo, 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 eventi premio per gestire gli eventi premio. L'esempio seguente 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 = RewardedAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded 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 RewardedAd ad = RewardedAdPreloader.pollAd(adUnitId);

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

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

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

Quando l'app raggiunge un posizionamento dell'annuncio e può chiamare il metodo show, chiama il metodo pollAd. Non chiamare il metodo pollAd nei callback di precaricamento o dopo aver controllato il metodo isAdAvailable per conservare un annuncio. Se devi esaminare i metadati dell'annuncio prima di mostrarlo, leggi le informazioni sulla risposta senza rimuovere l'annuncio dalla cache.

Ascoltare gli eventi degli annunci

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

Kotlin

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

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

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

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

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

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

Java

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

  rewardedAd.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded ad did show.
        }

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

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

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

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

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

Per passare il contesto dell'utente e dell'applicazione nei callback di verifica lato server (SSV), imposta le opzioni di verifica sull'oggetto annuncio prima di mostrare l'annuncio. Poiché i callback SSV arrivano al tuo server da Google senza stato della sessione, allega le seguenti stringhe facoltative. Google inoltra queste stringhe senza modifiche come parametri di query firmati nel callback SSV.

  • Parametro di query user_id: identifica l'utente a cui accreditare, ad esempio un ID account interno.
  • Parametro di query custom_data: contiene i dati dell'app, ad esempio il posizionamento del premio, il livello di gioco o un nonce generato dal server.

Se non imposti un valore, Google omette il parametro di query dal callback SSV.

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

Kotlin

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

Java

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

Sostituisci SAMPLE_CUSTOM_DATA_STRING con i tuoi dati personalizzati.

Punto chiave: il parametro di query custom_data è codificato in percentuale. Prima di analizzare il valore, decodifica l'URL della stringa sul server e verifica la firma del callback prima di considerare attendibili i parametri di query user_id o custom_data.

(Facoltativo) Ascoltare gli eventi di precaricamento

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

L'esempio seguente mostra come registrarsi per ricevere gli eventi di precaricamento degli annunci:

Kotlin

val preloadCallback =
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(TAG, "Rewarded preload ad $preloadId failed to load with error: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded preload ad $preloadId is not available")
    }

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

Java

PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
      }

      @Override
      public void onAdsExhausted(String preloadId) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is not available");
      }

      @Override
      public void onAdPreloaded(String preloadId, ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is available");
      }
    };

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

Quando il caricamento di un annuncio non riesce, GMA Next-Gen SDK precarica automaticamente gli annunci e riprova a inviare le richieste non riuscite per le configurazioni precaricate. Non richiamare le richieste di caricamento manuale nei callback di errore. Nei metodi di callback degli eventi precaricati, non chiamare i metodi pollAd, destroy o start. La chiamata di questi metodi nei callback può richiamare loop di caricamento ricorsivi.

(Facoltativo) Verificare la disponibilità degli annunci

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

Kotlin

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

Java

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

(Facoltativo) Impostare 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. Puoi impostare una dimensione del buffer personalizzata per aumentare o diminuire il numero di annunci mantenuti in memoria. Ti consigliamo di impostare una dimensione del buffer di due annunci precaricati. Se la maggior parte del traffico proviene da dispositivi con poca memoria, riduci la dimensione del buffer.

L'esempio seguente mostra come impostare una dimensione del buffer:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

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);
RewardedAdPreloader.start(adUnitId, preloadConfig);

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: Google mantiene in memoria un massimo di sei annunci precaricati. Questo limite è condiviso tra tutti i formati e gli ID di precaricamento.
  • Ti consigliamo di mantenere una dimensione del buffer di due per ogni ID di precaricamento.

(Facoltativo) Interrompere il precaricamento degli annunci

Mantieni attivo il precaricamento mentre l'app pubblica gli annunci. Durante questo periodo, non utilizzare il metodo destroy. Se non devi mostrare di nuovo gli annunci per un ID di precaricamento specifico nella sessione, puoi interrompere il precaricamento degli annunci. Per interrompere il caricamento degli annunci per un ID di precaricamento specifico, chiama il metodo destroy con un ID di precaricamento. La chiamata del metodo destroy rimuove dalla cache tutti gli annunci precaricati associati all'ID di precaricamento.

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

Kotlin

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

Java

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

(Facoltativo) Leggere le informazioni sulla risposta

Leggi le informazioni sulla risposta del prossimo annuncio precaricato senza rimuovere l'annuncio dalla cache. Se devi esaminare i metadati dell'annuncio prima di mostrarlo, leggi le informazioni sulla risposta anziché chiamare il metodo pollAd.

L'esempio seguente mostra come leggere le informazioni sulla risposta del prossimo annuncio precaricato:

Kotlin

val responseInfo = RewardedAdPreloader.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 = RewardedAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

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