Configurare gli annunci interstitial con premio

Gli annunci interstitial con premio sono un formato dell'annuncio a schermo intero che ti consente di offrire articoli in-app per gli annunci visualizzati tra le schermate o i livelli di gioco. A differenza degli annunci con premio, gli utenti non devono attivare la visualizzazione dell'annuncio. Per maggiori dettagli, consulta i case study di AdMob e la panoramica delle unità pubblicitarie interstitial con premio (beta).

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

Questa guida mostra come integrare gli annunci interstitial con premio con il precaricamento degli annunci in un'app React Native.

Prerequisiti

Prima di continuare, completa queste operazioni:

Android 

ca-app-pub-3940256099942544/5354046379

iOS 

ca-app-pub-3940256099942544/6978759866

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 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 interstitial con premio.

Avvia il precaricamento

Per iniziare a precaricare gli annunci, chiama il metodo RewardedInterstitialAdPreloader.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 startRewardedInterstitialAdPreloader(
  adUnitId: string,
  preloadId: string,
  customPreloadCallback?: PreloadCallback,
): boolean {
  const started = RewardedInterstitialAdPreloader.start(
    preloadId,
    {
      request: {adUnitId},
      bufferSize: 2,
    },
    {
      // Called when an ad is preloaded into the buffer.
      onAdPreloaded: (event) => {
        console.log(
          `Rewarded interstitial ad preloaded for ${event.preloadId}`,
        );
        customPreloadCallback?.onAdPreloaded?.(event);
      },
      // Called when an ad fails to preload.
      onAdFailedToPreload: (error: LoadAdError) => {
        console.error(
          'Failed to preload rewarded interstitial ad:',
          error.message,
        );
        customPreloadCallback?.onAdFailedToPreload?.(error);
      },
      // Called when all preloaded ads in the buffer have been shown.
      onAdsExhausted: () => {
        console.log('Rewarded interstitial ad buffer exhausted.');
        customPreloadCallback?.onAdsExhausted?.();
      },
    },
  );
  return started;
}

preloadId è una stringa che identifica in modo univoco una configurazione di precaricamento degli annunci. Se utilizzi un ID unità pubblicitaria per una singola configurazione di precaricamento nella tua app, utilizza questo ID unità pubblicitaria 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 non rimangono annunci precaricati nel buffer, Google Mobile Ads SDK for React Native richiama il callback onAdsExhausted.

Limiti della cache di precaricamento

Google Mobile Ads SDK for React Native applica un limite a livello di app per il numero totale di annunci precaricati:

  • Limite predefinito: Google conserva in memoria un massimo di sei annunci precaricati. Questo limite è condiviso tra tutti i formati e gli ID di precaricamento.
  • Buffer consigliato: due annunci precaricati 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 RewardedInterstitialAdPreloader.isAdAvailable. Per recuperare l'annuncio, chiama il metodo RewardedInterstitialAdPreloader.pollAd.

Per mostrare un annuncio, chiama il metodo show con un callback onUserEarnedReward per concedere il premio quando l'utente termina di guardare l'annuncio. 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 a schermo intero prima di mostrare l'annuncio:

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

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

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

export function peekRewardedInterstitialAdResponseInfo(
  preloadId: string,
): ResponseInfo | null {
  const responseInfo =
    RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo) {
    console.log(
      'Next preloaded rewarded interstitial 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 SSV

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 il metodo 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 interstitial con premio prima di mostrare un annuncio:

export function setServerSideVerificationRewardedInterstitial(
  ad: RewardedInterstitialAd,
) {
  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 RewardedInterstitialAdPreloader.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 destroyRewardedInterstitialAdPreloader(preloadId: string) {
  RewardedInterstitialAdPreloader.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

Questa sezione illustra l'implementazione completa del precaricamento degli annunci.

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 interstitial con premio precaricati:

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

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

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

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

  const handleShowAd = () => {
    setReward(null);
    setStatus('Showing preloaded ad...');
    showPreloadedRewardedInterstitialAd(
      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 Interstitial 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>
  );
}

Passaggi successivi

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