Configurare gli annunci con premio

Gli annunci con premio offrono agli utenti articoli in-app per l'interazione con annunci video, annunci demo e sondaggi. Per maggiori dettagli, consulta Panoramica delle unità pubblicitarie con premio.

Per eliminare la latenza di presentazione e assicurarsi che un annuncio sia disponibile quando un utente guadagna un premio, Google Mobile Ads SDK for React Native utilizza il precaricamento degli annunci per gestire il caricamento in background, la memorizzazione nella cache e il ripristino del buffer.

Questa guida mostra come integrare gli annunci con premio in un'app nativa React Native.

Prerequisiti

Prima di continuare, completa queste operazioni:

Android 

ca-app-pub-3940256099942544/5224354917

iOS 

ca-app-pub-3940256099942544/1712485313

Informazioni sul precaricamento degli annunci

Il precaricamento degli annunci in Google Mobile Ads SDK for React Native 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 pubblicazione degli annunci.
  • Ricaricamento automatico: carica un nuovo annuncio quando ne viene recuperato uno dalla cache.
  • Nuovi tentativi gestiti: carica un nuovo annuncio quando non è possibile caricarne uno.
  • 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.

Per caricare gli annunci manualmente, consulta Carica un singolo annuncio con premio.

Avvia il precaricamento

Per iniziare a precaricare gli annunci, chiama il metodo RewardedAdPreloader.start e passa il valore preloadId, le impostazioni di configurazione e i callback degli eventi per monitorare le modifiche allo stato del buffer:

export function startRewardedAdPreloader(
  adUnitId: string,
  preloadId: string,
  customPreloadCallback?: PreloadCallback,
): boolean {
  const started = RewardedAdPreloader.start(
    preloadId,
    {
      request: {adUnitId},
      bufferSize: 2,
    },
    {
      // Called when an ad is preloaded into the buffer.
      onAdPreloaded: (event) => {
        console.log(`Rewarded ad preloaded for ${event.preloadId}`);
        customPreloadCallback?.onAdPreloaded?.(event);
      },
      // Called when an ad fails to preload.
      onAdFailedToPreload: (error: LoadAdError) => {
        console.error('Failed to preload rewarded ad:', error.message);
        customPreloadCallback?.onAdFailedToPreload?.(error);
      },
      // Called when all preloaded ads in the buffer have been shown.
      onAdsExhausted: () => {
        console.log('Rewarded ad buffer exhausted.');
        customPreloadCallback?.onAdsExhausted?.();
      },
    },
  );
  return started;
}

Un ID di precaricamento è una stringa che identifica in modo univoco una configurazione di precaricamento degli annunci. Se utilizzi l'ID unità pubblicitaria per una singola configurazione di precaricamento nella tua app, puoi utilizzarlo come ID di precaricamento. Se la tua app richiede più precaricatori per lo stesso ID unità pubblicitaria, passa stringhe distinte per ogni ID precaricamento.

Quando la tua app esegue il polling di un annuncio precaricato dal buffer, Google Mobile Ads SDK for React Native richiede un annuncio sostitutivo in background per riempire nuovamente il buffer. Se nel buffer non rimangono annunci precaricati, Google Mobile Ads SDK for React Native richiama onAdsExhausted.

Limiti della cache di precaricamento

Google Mobile Ads SDK for React Native 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 conserva in memoria un massimo di sei annunci precaricati. Questo limite è condiviso tra tutti i formati e gli ID di precaricamento.
  • Dimensione del buffer consigliata: due per ogni ID di precaricamento.

Se la tua app raggiunge il limite a livello di app, le richieste in background per gli annunci precaricati vengono messe in pausa finché gli annunci esistenti non vengono estratti dalla cache o eliminati. Il precaricamento viene inoltre messo in pausa temporaneamente mentre un annuncio a schermo intero viene visualizzato attivamente sullo schermo.

Esegui il polling e mostra l'annuncio

Prima di mostrare un annuncio, verifica che sia disponibile chiamando il metodo RewardedAdPreloader.isAdAvailable. Per recuperare l'annuncio, chiama il metodo RewardedAdPreloader.pollAd.

Per ascoltare gli eventi di presentazione, come la chiusura degli annunci o gli errori di visualizzazione, imposta la proprietà adEventCallback nell'istanza dell'annuncio prima di chiamare il metodo show:

L'esempio seguente verifica la disponibilità degli annunci e rimane in ascolto degli eventi di presentazione prima di mostrare l'annuncio:

export function showPreloadedRewardedAd(
  preloadId: string,
  onRewardEarned: (reward: Reward) => void,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!RewardedAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded rewarded ad available right now.');
    return;
  }

  const ad = RewardedAdPreloader.pollAd(preloadId);
  if (!ad) {
    return;
  }

  ad.adEventCallback = {
    // Called when the ad is presented on screen.
    onAdShowedFullScreenContent: () => {
      console.log('Preloaded rewarded ad showed full screen content.');
      customAdEventCallback?.onAdShowedFullScreenContent?.();
    },
    // Called when the ad is closed by the user.
    onAdDismissedFullScreenContent: () => {
      console.log('Preloaded rewarded ad dismissed full screen content.');
      customAdEventCallback?.onAdDismissedFullScreenContent?.();
      ad.destroy();
    },
    // Called when presentation fails.
    onAdFailedToShowFullScreenContent: (error) => {
      console.error('Failed to show preloaded rewarded ad:', error);
      customAdEventCallback?.onAdFailedToShowFullScreenContent?.(error);
      ad.destroy();
    },
    // Called when an impression is recorded.
    onAdImpression: () => {
      console.log('Preloaded rewarded ad recorded an impression.');
      customAdEventCallback?.onAdImpression?.();
    },
    // Called when the user taps the ad.
    onAdClicked: () => {
      console.log('Preloaded rewarded ad was clicked.');
      customAdEventCallback?.onAdClicked?.();
    },
    // Called when the ad is estimated to have earned money.
    onAdPaid: (adValue) => {
      console.log(
        `Preloaded rewarded ad paid: ${adValue.amountMicros}` +
          ` ${adValue.currencyCode}`,
      );
      customAdEventCallback?.onAdPaid?.(adValue);
    },
  };

  ad.show(onRewardEarned);
}

Per liberare memoria e risorse, chiama il metodo ad.destroy nei callback onAdDismissedFullScreenContent e onAdFailedToShowFullScreenContent.

Leggi le informazioni sulla risposta

Per esaminare le informazioni sulla risposta per l'annuncio precaricato successivo senza rimuoverlo dalla cache, chiama il metodo RewardedAdPreloader.peekAdResponseInfo:

export function peekRewardedAdResponseInfo(
  preloadId: string,
): ResponseInfo | null {
  const responseInfo = RewardedAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo) {
    console.log('Next preloaded rewarded ad response info:', responseInfo);
  }
  return responseInfo;
}

Se è disponibile un annuncio, il metodo peekAdResponseInfo restituisce un oggetto ResponseInfo contenente informazioni sull'origine annuncio caricata e sugli adattatori di rete.

(Facoltativo) Convalida i callback di verifica lato server

Se la tua app richiede parametri di verifica personalizzati, come un ID utente o metadati dei premi personalizzati, nei callback di verifica lato server (SSV), imposta la proprietà serverSideVerificationOptions nell'istanza dell'annuncio sottoposta a polling prima di chiamare show.

I valori impostati vengono trasmessi ai parametri di query di callback SSV:

  • userId: passa al parametro di query user_id per identificare l'utente.
  • customData: passa al parametro di query custom_data per inoltrare i metadati personalizzati.

L'esempio seguente imposta ServerSideVerificationOptions (customData e userId) su un oggetto annuncio con premio prima di mostrare un annuncio:

export function setServerSideVerificationRewarded(ad: RewardedAd) {
  ad.serverSideVerificationOptions = {
    userId: 'user_123',
    customData: 'sample_custom_data',
  };
}

Esegui la pulizia delle risorse

Se non hai più bisogno di mostrare annunci per un ID di precaricamento specifico per il resto della sessione, chiama il metodo RewardedAdPreloader.destroy. Questo processo interrompe il precaricamento per l'ID di precaricamento e libera dalla memoria gli annunci precaricati non utilizzati.

L'esempio seguente interrompe il precaricamento:

export function destroyRewardedAdPreloader(preloadId: string) {
  RewardedAdPreloader.destroy(preloadId);
}

Dopo che l'utente ha chiuso l'annuncio o se l'annuncio non viene mostrato, elimina le singole istanze di annunci sottoposti a polling. Per maggiori dettagli, consulta Esegui il polling e mostra l'annuncio.

Visualizza l'esempio completo

Il seguente componente di esempio avvia il precaricamento al momento del montaggio, monitora i conteggi degli annunci disponibili e fornisce controlli per mostrare gli annunci con premio precaricati:

export function RewardedScreen() {
  const [numAdsAvailable, setNumAdsAvailable] = useState<number>(0);
  const [status, setStatus] = useState<string>('Preloader idle.');
  const [reward, setReward] = useState<string | null>(null);

  const refreshAdCount = () => {
    const count = RewardedAdPreloader.getNumAdsAvailable(PRELOAD_ID);
    setNumAdsAvailable(count);
  };

  useEffect(() => {
    // Start preloading ads on component mount
    const started = startRewardedAdPreloader(REWARDED_AD_UNIT_ID, PRELOAD_ID, {
      onAdPreloaded: () => {
        refreshAdCount();
        setStatus('Rewarded ad preloaded into buffer.');
      },
      onAdFailedToPreload: (error) => {
        setStatus(`Failed to preload rewarded ad: ${error.message}`);
      },
      onAdsExhausted: () => {
        refreshAdCount();
        setStatus('Preload buffer exhausted for rewarded ads.');
      },
    });
    if (started) {
      setStatus('Preloader started.');
    }

    // Clean up preloader resources on component unmount
    return () => {
      destroyRewardedAdPreloader(PRELOAD_ID);
    };
  }, []);

  const handleShowAd = () => {
    setReward(null);
    setStatus('Showing preloaded ad...');
    showPreloadedRewardedAd(
      PRELOAD_ID,
      (userReward) => {
        setReward(`${userReward.amount} ${userReward.type}`);
      },
      {
        onAdDismissedFullScreenContent: () => {
          setStatus('Ad dismissed.');
        },
        onAdFailedToShowFullScreenContent: (error) => {
          setStatus(`Failed to show preloaded ad: ${error.message}`);
        },
      },
    );
    refreshAdCount();
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Preload Rewarded Ads</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <Text style={styles.status}>Ads Available: {numAdsAvailable}</Text>
      {reward && <Text style={styles.rewardText}>Earned: {reward}</Text>}
      <View style={styles.buttonGroup}>
        <Button
          title="Show Preloaded Ad"
          onPress={handleShowAd}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

Sostituisci quanto segue:

  • REWARDED_AD_UNIT_ID con l'ID unità pubblicitaria.
  • PRELOAD_ID con l'ID del precaricatore.

Passaggi successivi

Dopo aver integrato gli annunci con premio, consulta i seguenti argomenti: