O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Configurar anúncios de abertura do app

Os anúncios de abertura do app aparecem quando os usuários abrem ou retornam ao seu app e podem ser fechados a qualquer momento. Para gerar receita com a tela de carregamento do seu app, use anúncios de abertura do app. Para mais detalhes, consulte Orientações e práticas recomendadas para anúncios de abertura do app.

Este guia explica como integrar anúncios de abertura do app a um aplicativo React Native.

Pré-requisitos

Antes de continuar, faça o seguinte:

Configure o Google Mobile Ads SDK for React Native.
Ative os anúncios de teste e use este bloco de anúncios de teste:

Android

ca-app-pub-3940256099942544/9257395921

iOS

ca-app-pub-3940256099942544/5575463023

Entender o pré-carregamento de anúncios

O pré-carregamento de anúncios no Google Mobile Ads SDK for React Native automatiza o carregamento e o armazenamento em cache de anúncios.

O pré-carregamento de anúncios oferece os seguintes benefícios:

Gerenciamento de referências: mantém as referências até que os anúncios sejam mostrados.
Recarga automática: carrega um novo anúncio quando um é recuperado do cache.
Tentativas gerenciadas: carrega um novo anúncio quando um falha.
Tratamento de expiração: atualiza os anúncios antes que eles expirem.
Otimização de cache: otimiza a ordem do cache para exibir o anúncio de maior prioridade.

Para carregar anúncios manualmente, consulte o guia Carregar um único anúncio de abertura do app.

Iniciar pré-carregamento

Para começar a pré-carregar anúncios, chame o método AppOpenAdPreloader.start e transmita o valor de preloadId, as definições de configuração e os callbacks de evento para monitorar as mudanças no estado do 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;
}

Um preloadId é uma string que identifica de forma exclusiva uma configuração de pré-carregamento de anúncios. Se o adUnitId for usado para apenas uma configuração de pré-carregamento no app, você poderá usar esse ID do bloco de anúncios como o ID de pré-carregamento. Se o app exigir vários pré-carregadores para o mesmo ID de bloco de anúncios, transmita strings diferentes para cada ID de pré-carregamento.

Quando o app busca um anúncio pré-carregado do buffer, o Google Mobile Ads SDK for React Native solicita um anúncio de substituição em segundo plano para preencher o buffer novamente. Se não houver anúncios pré-carregados no buffer, o Google Mobile Ads SDK for React Native vai invocar o callback onAdsExhausted.

Limites de cache de pré-carregamento

O Google Mobile Ads SDK for React Native aplica um limite em todo o app para o número total de anúncios pré-carregados:

Limite padrão: o Google mantém no máximo seis anúncios pré-carregados na memória.
Recomendamos manter um tamanho de buffer de dois para cada ID de pré-carregamento.

Se o app atingir o limite, as solicitações em segundo plano para anúncios pré-carregados serão pausadas até que os anúncios atuais sejam consultados e mostrados ou destruídos.

Sondar e mostrar o anúncio

Para verificar se há anúncios pré-carregados disponíveis e recuperar uma instância de anúncio, chame o método AppOpenAdPreloader.pollAd.

Para detectar eventos de apresentação em tela cheia, registre callbacks na propriedade adEventCallback da instância AppOpenAd retornada antes de chamar o método 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();
}

Para liberar memória e recursos, chame o método ad.destroy nos callbacks onAdDismissedFullScreenContent e onAdFailedToShowFullScreenContent quando um usuário dispensar um anúncio ou quando o anúncio não for exibido.

Ler as informações da resposta

Para inspecionar os detalhes do próximo anúncio pré-carregado sem removê-lo do cache, chame o método 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;
}

Gerenciar anúncios de abertura do app com um administrador no nível do app

Como os anúncios de abertura do app são apresentados globalmente durante o lançamento do app e as transições em primeiro plano, recomendamos gerenciar o estado do ciclo de vida do pré-carregador em um gerenciador no nível do app, fora da árvore de componentes do React.

Usar um gerenciador no nível do app oferece várias vantagens importantes:

Mantém o estado do pré-carregador independente da navegação de tela individual e do ciclo de vida do componente.
Centraliza callbacks de eventos de anúncio, rastreamento de estado e limpeza em uma única instância compartilhada no app.
Controla quando os eventos em primeiro plano são detectados, evitando apresentações duplicadas após a dispensa do anúncio.

O exemplo a seguir implementa um gerenciador no nível do app usando o objeto 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();
  }
}

Detectar eventos do app em primeiro plano

Para mostrar anúncios de display quando o app voltar ao primeiro plano, registre um listener change no módulo AppState no componente raiz do app, como App.tsx. Verifique quando o estado muda para active. Por exemplo, chame o método start na instância do gerenciador de anúncios no componente App.tsx.

A apresentação de sobreposições de anúncios ou páginas de destino, como a exibição de anúncios de tela cheia ou o toque em um anúncio de banner, coloca o aplicativo em segundo plano. Quando o usuário retorna ao aplicativo, o app recebe um novo evento de estado active. Para evitar uma apresentação de anúncio não intencional ou um loop em que o retorno de um anúncio apresenta um anúncio de abertura do app do cache, faça o seguinte:

Remova o listener de eventos AppState antes de mostrar um anúncio de tela cheia.
Para garantir que a reprodução seja retomada se o usuário dispensar o anúncio ou se ele não for exibido, adicione o listener de eventos AppState novamente nos callbacks onAdDismissedFullScreenContent e onAdFailedToShowFullScreenContent.

Para um exemplo completo de como controlar quando os listeners de eventos em primeiro plano são pausados e retomados, consulte a implementação de AppOpenAdManager.

Saiba mais sobre inicializações a frio e telas de carregamento

Uma inicialização a frio ocorre quando o app é iniciado do zero, por exemplo, quando um usuário abre o app pela primeira vez ou depois que o dispositivo fecha o app para liberar memória. Durante uma inicialização a frio, não há um anúncio de abertura do app carregado para ser mostrado em seguida.

Devido a atrasos na solicitação de anúncio, os usuários podem interagir com o app antes que um anúncio apareça. Mostre anúncios de abertura do app em inicializações a frio apenas em uma tela de carregamento enquanto os recursos de link para app são carregados. Se os recursos terminarem de carregar e o usuário chegar ao conteúdo principal antes do carregamento de anúncios, não mostre o anúncio.

Limpar recursos

Quando o pré-carregamento não for mais necessário para um ID de tela ou de bloco de anúncios, como ao sair de uma tela que pré-carrega anúncios, chame o método AppOpenAdPreloader.destroy para liberar recursos do pré-carregador e evitar que objetos de anúncio não utilizados sejam mantidos na memória:

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

Além de destruir a fila do pré-carregador, destrua as instâncias individuais de anúncios pesquisados quando um usuário dispensar um anúncio ou quando ele não for exibido. Para mais detalhes, consulte Sondar e mostrar o anúncio.

Ver o exemplo completo

O exemplo de componente a seguir inicia o pré-carregamento na montagem, rastreia as contagens de anúncios disponíveis e fornece controles para mostrar anúncios de abertura do app pré-carregados:

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>
  );
}

Substitua:

APP_OPEN_AD_UNIT_ID pelo ID do bloco de anúncios.
PRELOAD_ID pelo ID do pré-carregador.

Próximas etapas

Depois de integrar os anúncios de abertura do app, confira os seguintes tópicos:

Configurar anúncios de abertura do app Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.