Configurare gli annunci apertura app

Gli annunci apertura app vengono visualizzati quando gli utenti aprono o tornano alla tua app. Gli utenti possono chiudere gli annunci apertura app in qualsiasi momento. Per monetizzare la schermata di caricamento dell'app, utilizza gli annunci apertura app. Per maggiori dettagli, consulta Indicazioni e best practice per gli annunci apertura app.

Questa guida spiega come integrare gli annunci apertura app in un'app React Native.

Prerequisiti

Prima di continuare, completa queste operazioni:

Android 

ca-app-pub-3940256099942544/9257395921

iOS 

ca-app-pub-3940256099942544/5575463023

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 apertura app.

Avvia il precaricamento

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

Un preloadId è una stringa che identifica in modo univoco una configurazione di precaricamento degli annunci. Se l'unità pubblicitaria adUnitId viene utilizzata per una sola configurazione di precaricamento nella tua app, puoi utilizzare l'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.
  • Ti consigliamo di mantenere una dimensione del buffer pari a 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 sottoposti a polling e visualizzati o eliminati.

Esegui il polling e mostra l'annuncio

Per verificare la presenza di annunci precaricati disponibili e recuperare un'istanza di annuncio, chiama il metodo AppOpenAdPreloader.pollAd.

Per ascoltare gli eventi di presentazione a schermo intero, registra i callback sulla proprietà adEventCallback dell'istanza AppOpenAd restituita prima di chiamare il metodo show:

export function showPreloadedAppOpenAd(
  preloadId: string,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!AppOpenAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded app open ad available right now.');
    return;
  }

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

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

  ad.show();
}

Per liberare memoria e risorse, chiama il metodo ad.destroy nei callback onAdDismissedFullScreenContent e onAdFailedToShowFullScreenContent quando un utente chiude un annuncio o l'annuncio non viene mostrato.

Leggi le informazioni sulla risposta

Per esaminare i dettagli del successivo annuncio precaricato senza rimuoverlo dalla cache, chiama il metodo AppOpenAdPreloader.peekAdResponseInfo:

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

Gestisci gli annunci apertura app con un gestore a livello di app

Poiché gli annunci apertura app vengono presentati a livello globale durante l'avvio dell'app e le transizioni in primo piano, ti consigliamo di gestire lo stato del ciclo di vita del precaricatore in un gestore a livello di app esterno all'albero dei componenti React.

L'utilizzo di un amministratore a livello di app offre diversi vantaggi principali:

  • Mantiene lo stato del precaricatore indipendente dalla navigazione nelle singole schermate e dal ciclo di vita dei componenti.
  • Centralizza i callback degli eventi degli annunci, il monitoraggio dello stato e la pulizia in un'unica istanza condivisa nell'app.
  • Controlla quando vengono ascoltati gli eventi in primo piano, evitando presentazioni duplicate alla chiusura dell'annuncio.

L'esempio seguente implementa un gestore a livello di app utilizzando l'oggetto AppOpenAdPreloader:

export class AppOpenAdManager {
  private adUnitId: string;
  private preloadId: string;
  private appStateSubscription?: NativeEventSubscription;
  private startTimeoutId?: ReturnType<typeof setTimeout>;

  constructor(adUnitId: string, preloadId: string) {
    this.adUnitId = adUnitId;
    this.preloadId = preloadId;
  }

  start(): boolean {
    if (!AppOpenAdPreloader.getConfiguration(this.preloadId)) {
      AppOpenAdPreloader.start(
        this.preloadId,
        {
          request: {adUnitId: this.adUnitId},
          bufferSize: 2,
        },
        {
          onAdPreloaded: (event) => {
            console.log(`App open ad preloaded for ${event.preloadId}`);
          },
          onAdFailedToPreload: (error: LoadAdError) => {
            console.error('Failed to preload app open ad:', error.message);
          },
          onAdsExhausted: () => {
            console.log('App open ad buffer exhausted.');
          },
        },
      );
    }

    if (!this.appStateSubscription && !this.startTimeoutId) {
      // Delay attaching the listener to ensure native dismissal transitions complete
      this.startTimeoutId = setTimeout(() => {
        this.startTimeoutId = undefined;
        if (!this.appStateSubscription) {
          this.appStateSubscription = AppState.addEventListener(
            'change',
            (nextAppState: AppStateStatus) => {
              if (nextAppState === 'active') {
                this.showAdIfAvailable();
              }
            },
          );
        }
      }, APP_STATE_LISTENER_DELAY_MS);
    }

    return true;
  }

  pause(): void {
    if (this.startTimeoutId) {
      clearTimeout(this.startTimeoutId);
      this.startTimeoutId = undefined;
    }
    this.appStateSubscription?.remove();
    this.appStateSubscription = undefined;
  }

  stop(): void {
    this.pause();
    AppOpenAdPreloader.destroy(this.preloadId);
  }

  showAdIfAvailable() {
    if (!AppOpenAdPreloader.isAdAvailable(this.preloadId)) {
      console.log('App open ad is not preloaded or available right now.');
      return;
    }

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

    // Pause listener while presenting the ad
    this.pause();

    ad.adEventCallback = {
      onAdShowedFullScreenContent: () => {
        console.log('Preloaded app open ad showed full screen content.');
      },
      onAdDismissedFullScreenContent: () => {
        console.log('Preloaded app open ad dismissed full screen content.');
        ad.destroy();
        this.start();
      },
      onAdFailedToShowFullScreenContent: (error) => {
        console.error('Failed to show preloaded app open ad:', error);
        ad.destroy();
        this.start();
      },
    };

    ad.show();
  }
}

Ascolta gli eventi che mettono in primo piano l'app

Per visualizzare gli annunci display quando l'app torna in primo piano, registra un listener change sul modulo AppState nel componente principale dell'app, ad esempio App.tsx. Controlla quando lo stato passa a active. Ad esempio, chiama il metodo start nell'istanza di Ad Manager nel componente App.tsx.

La visualizzazione di overlay annuncio o pagine di destinazione, ad esempio la visualizzazione di annunci a schermo intero o il tocco di un annuncio banner, spinge l'applicazione in background. Quando l'utente torna alla tua applicazione, l'app riceve un nuovo evento di stato active. Per evitare una presentazione o un loop involontario degli annunci in cui il ritorno da un annuncio presenta un annuncio apertura app dalla cache, segui questi passaggi:

  1. Rimuovi il listener di eventi AppState prima di presentare un annuncio a schermo intero.
  2. Per assicurarti che l'ascolto riprenda indipendentemente dal fatto che un utente chiuda l'annuncio o che l'annuncio non venga mostrato, aggiungi di nuovo il listener di eventi AppState nei callback onAdDismissedFullScreenContent e onAdFailedToShowFullScreenContent.

Per un esempio completo di controllo di quando i listener di eventi in primo piano vengono messi in pausa e ripresi, consulta l'implementazione di AppOpenAdManager.

Scopri di più sugli avvii completi e sulle schermate di caricamento

Un avvio a freddo si verifica quando l'app viene avviata da zero, ad esempio quando un utente apre l'app per la prima volta o dopo che il dispositivo chiude l'app per liberare memoria. Durante un avvio a freddo, non hai un annuncio apertura app caricato in precedenza da mostrare successivamente.

A causa dei ritardi nelle richieste di annunci, gli utenti potrebbero interagire con la tua app prima che venga visualizzato un annuncio. Mostra gli annunci apertura app con avvio a freddo solo da una schermata di caricamento mentre gli asset per app vengono caricati. Se il caricamento degli asset termina e l'utente raggiunge i contenuti principali prima del caricamento dell'annuncio, non mostrare l'annuncio.

Esegui la pulizia delle risorse

Quando il precaricamento non è più necessario per uno schermo o un ID unità pubblicitaria, ad esempio quando esci da una schermata che precarica gli annunci, chiama il metodo AppOpenAdPreloader.destroy per rilasciare le risorse del precaricatore ed evitare di conservare in memoria oggetti annuncio inutilizzati:

export function destroyAppOpenAdPreloader(preloadId: string) {
  AppOpenAdPreloader.destroy(preloadId);
}

Oltre a eliminare la coda del precaricatore, assicurati di eliminare le singole istanze di annunci sottoposti a polling quando un utente chiude un annuncio o l'annuncio non viene mostrato. Per i 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 i controlli per mostrare gli annunci apertura app precaricati:

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

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

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

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

  const handleShowAd = () => {
    setStatus('Showing preloaded ad...');
    showPreloadedAppOpenAd(PRELOAD_ID, {
      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 App Open 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={handleShowAd}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

Sostituisci quanto segue:

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

Passaggi successivi

Dopo aver integrato gli annunci apertura app, consulta i seguenti argomenti: