Configurare gli annunci interstitial

Gli annunci interstitial sono annunci a schermo intero che vengono visualizzati nei punti di transizione dell'app, ad esempio tra una schermata e l'altra o durante la pausa tra i livelli di un gioco. Gli utenti possono toccare l'annuncio per visitare la destinazione o chiuderlo e tornare all'app. Per maggiori dettagli, consulta le indicazioni sugli annunci interstitial e un case study.

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 in un'app React Native.

Prerequisiti

Prima di continuare, completa queste operazioni:

Android 

ca-app-pub-3940256099942544/1033173712

iOS 

ca-app-pub-3940256099942544/4411468910

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 la guida Carica un singolo annuncio interstitial.

Avvia il precaricamento

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

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, 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 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.
  • 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 InterstitialAdPreloader.isAdAvailable. Per recuperare l'annuncio, chiama il metodo InterstitialAdPreloader.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 a schermo intero prima di mostrare l'annuncio:

export function showPreloadedAd(
  preloadId: string,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (InterstitialAdPreloader.isAdAvailable(preloadId)) {
    const ad = InterstitialAdPreloader.pollAd(preloadId);
    if (ad) {
      ad.adEventCallback = {
        // Called when the ad is presented on screen.
        onAdShowedFullScreenContent: () => {
          console.log('Preloaded interstitial ad showed full screen content.');
          customAdEventCallback?.onAdShowedFullScreenContent?.();
        },
        // Called when the ad is closed by the user.
        onAdDismissedFullScreenContent: () => {
          console.log('Preloaded interstitial ad dismissed.');
          customAdEventCallback?.onAdDismissedFullScreenContent?.();
          ad.destroy();
        },
        // Called when presentation fails.
        onAdFailedToShowFullScreenContent: (error) => {
          console.error('Preloaded interstitial ad failed to show:', error);
          customAdEventCallback?.onAdFailedToShowFullScreenContent?.(error);
          ad.destroy();
        },
        // Called when an impression is recorded.
        onAdImpression: () => {
          console.log('Preloaded interstitial ad recorded an impression.');
          customAdEventCallback?.onAdImpression?.();
        },
        // Called when the user taps the ad.
        onAdClicked: () => {
          console.log('Preloaded interstitial ad was clicked.');
          customAdEventCallback?.onAdClicked?.();
        },
        // Called when the ad is estimated to have earned money.
        onAdPaid: (adValue) => {
          console.log(
            `Preloaded interstitial ad paid: ${adValue.amountMicros}` +
              ` ${adValue.currencyCode}`,
          );
          customAdEventCallback?.onAdPaid?.(adValue);
        },
      };
      ad.show();
    }
  } else {
    console.log('No preloaded interstitial ad available in buffer.');
  }
}

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 InterstitialAdPreloader.peekAdResponseInfo:

export function peekPreloadedAdResponseInfo(preloadId: string) {
  if (InterstitialAdPreloader.isAdAvailable(preloadId)) {
    const responseInfo = InterstitialAdPreloader.peekAdResponseInfo(preloadId);
    if (responseInfo) {
      console.log('Next preloaded ad response info:', responseInfo);
    }
  }
}

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

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 InterstitialAdPreloader.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 destroyPreloader(preloadId: string) {
  InterstitialAdPreloader.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 interstitial precaricati:

export function InterstitialScreen() {
  const [numAdsAvailable, setNumAdsAvailable] = useState<number>(0);
  const [status, setStatus] = useState<string>('Initializing Preloader...');

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

  useEffect(() => {
    // Start preloading interstitial ads on component mount
    startPreloader(INTERSTITIAL_AD_UNIT_ID, PRELOAD_ID, {
      onAdPreloaded: () => {
        refreshAdCount();
        setStatus('Ad preloaded and ready!');
      },
      onAdFailedToPreload: (error) => {
        setStatus(`Preload failed: ${error.message}`);
      },
      onAdsExhausted: () => {
        refreshAdCount();
        setStatus('Preload buffer exhausted.');
      },
    });
    setStatus('Preloader started.');

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

  const handleShow = () => {
    showPreloadedAd(PRELOAD_ID, {
      onAdDismissedFullScreenContent: () => {
        setStatus('Ad dismissed.');
      },
      onAdFailedToShowFullScreenContent: (error) => {
        setStatus(`Failed to show ad: ${error.message}`);
      },
    });
    setStatus('Showing preloaded ad...');
    refreshAdCount();
  };

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

Sostituisci quanto segue:

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

Passaggi successivi

Dopo aver integrato gli annunci interstitial, consulta i seguenti argomenti: