Carregar um único anúncio 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. Veja mais detalhes em

Orientação 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:

Android 

ca-app-pub-3940256099942544/9257395921

iOS 

ca-app-pub-3940256099942544/5575463023

Carregar um anúncio

Para carregar um anúncio de abertura do app, chame o método load.

O exemplo a seguir carrega um anúncio de abertura do app em caso de sucesso e registra um erro em caso de falha:

export async function loadAppOpenAd(
  adUnitId: string,
): Promise<AppOpenAd | null> {
  try {
    const ad = await AppOpenAd.load({adUnitId});
    return ad;
  } catch (error) {
    const loadError = error as LoadAdError;
    console.error('Failed to load app open ad:', loadError.message);
    return null;
  }
}

Detectar eventos de anúncios

Antes de mostrar o anúncio, defina o listener adEventCallback na instância AppOpenAd carregada. Esse listener recebe callbacks de eventos de ciclo de vida do anúncio, como a exibição do anúncio na tela ou um usuário tocando nele. Para ver os callbacks disponíveis, consulte AdEventCallback.

O exemplo a seguir define callbacks para detectar eventos de anúncio:

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

Este exemplo também usa o método destroy quando um usuário fecha o anúncio ou quando ele não é exibido. Esse processo libera os recursos usados pelo anúncio.

Mostrar o anúncio

Para mostrar um anúncio de abertura do app, chame o método show:

export function showAppOpenAd(ad: AppOpenAd) {
  ad.show();
}

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

Recomendamos que você gerencie os anúncios de abertura do app em um gerenciador no nível do app fora da árvore de componentes do React. Como os anúncios de abertura do app aparecem globalmente quando o usuário abre ou retorna ao app, um gerenciador no nível do app mantém os anúncios separados da interface do usuário.

O exemplo a seguir cria uma instância SingleLoadAppOpenAdManager que carrega um anúncio, detecta eventos de anúncio e verifica a disponibilidade de anúncios:

export class SingleLoadAppOpenAdManager {
  private ad: AppOpenAd | null = null;
  private loadTime = 0;
  private isShowingAd = false;

  async loadAd(adUnitId: string) {
    // Avoid re-loading if an ad is already loaded or showing.
    if (this.ad) {
      return;
    }
    try {
      this.ad = await AppOpenAd.load({adUnitId});
      this.loadTime = Date.now();
      this.ad.adEventCallback = {
        onAdDismissedFullScreenContent: () => {
          this.ad?.destroy();
          this.ad = null;
          this.isShowingAd = false;
          // Preload the next ad for future foreground transitions.
          this.loadAd(adUnitId);
        },
        onAdFailedToShowFullScreenContent: () => {
          // An ad object that fails to present is consumed and cannot be reused.
          // Clean up native resources and preload a new ad for future events.
          this.ad?.destroy();
          this.ad = null;
          this.isShowingAd = false;
          this.loadAd(adUnitId);
        },
      };
    } catch (error) {
      console.error('Failed to load app open ad:', error);
    }
  }

  showAdIfAvailable() {
    if (!this.ad || !this.isAdAvailable()) {
      console.warn(
        'App open ad cannot be shown: ad is not loaded or has expired.',
      );
      return;
    }
    if (this.isShowingAd) {
      console.warn('App open ad cannot be shown: an ad is already displaying.');
      return;
    }

    this.ad.show();
    this.isShowingAd = true;
  }

  isAdAvailable(): boolean {
    // App Open ads expire after 4 hours per Google Mobile Ads policy.
    const FOUR_HOURS_IN_MS = 4 * 60 * 60 * 1000;
    return this.ad !== null && Date.now() - this.loadTime < FOUR_HOURS_IN_MS;
  }
}

Um gerenciador no nível do app ajuda você a:

  • Mantenha o estado do anúncio independente da navegação na tela e dos ciclos de vida dos componentes.
  • Acompanhe o estado de apresentação do anúncio em eventos de linha de execução nativa.
  • Gerencie as transições do app para o primeiro plano para evitar a exibição de anúncios repetidos.
  • Pré-carregue anúncios em segundo plano para que eles fiquem disponíveis quando o app for aberto.
  • Verifique o limite de validade de quatro horas para evitar a veiculação de anúncios expirados.
  • Combine o carregamento, a exibição e a limpeza de recursos de anúncio.

Detectar eventos do app em primeiro plano

Para mostrar anúncios de display quando o app voltar ao primeiro plano, use o módulo AppState para detectar mudanças de estado na raiz do app, por exemplo, no arquivo App.tsx. Faça o seguinte:

  1. Registre um listener AppState para o evento 'change'.
  2. Quando o estado mudar para 'active', chame o método showAdIfAvailable na instância do gerenciador de anúncios.

O exemplo a seguir detecta eventos em primeiro plano do app e mostra um anúncio, se disponível:

export function setupAppOpenAdForegroundListener(adManager: {
  showAdIfAvailable: () => void;
}): NativeEventSubscription {
  return AppState.addEventListener('change', (nextAppState: AppStateStatus) => {
    if (nextAppState === 'active') {
      adManager.showAdIfAvailable();
    }
  });
}

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. Para evitar uma experiência do usuário ruim, mostre anúncios de abertura do app em inicializações a frio somente em uma tela de carregamento enquanto os recursos do 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.

Configurar uma tela de teste

Para testar anúncios de forma interativa ou mostrá-los em uma tela específica, gerencie a instância do anúncio no estado do componente.

O exemplo a seguir integra um anúncio de abertura do app a um componente do React Native com um hook de limpeza useEffect. Se o componente for desmontado antes da exibição do anúncio, esse hook vai liberar recursos nativos.

export function AppOpenSingleLoadScreen() {
  const [ad, setAd] = useState<AppOpenAd | null>(null);
  const [isLoaded, setIsLoaded] = useState(false);
  const [status, setStatus] = useState<string>('Idle');

  useEffect(() => {
    return () => {
      ad?.destroy();
    };
  }, [ad]);

  const handleLoad = async () => {
    setStatus('Loading App Open ad...');
    const loadedAd = await loadAppOpenAd(APP_OPEN_AD_UNIT_ID);
    if (loadedAd) {
      registerAdEvents(loadedAd);
      const onDismiss =
        loadedAd.adEventCallback?.onAdDismissedFullScreenContent;
      loadedAd.adEventCallback = {
        ...loadedAd.adEventCallback,
        onAdDismissedFullScreenContent: () => {
          onDismiss?.();
          setStatus('Ad dismissed.');
        },
      };
      setAd((prevAd) => {
        prevAd?.destroy();
        return loadedAd;
      });
      setIsLoaded(true);
      setStatus('App Open ad loaded!');
    } else {
      setStatus('Failed to load App Open ad.');
    }
  };

  const handleShow = () => {
    if (ad) {
      showAppOpenAd(ad);
      setIsLoaded(false);
    }
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>App Open Ad</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <View style={styles.buttonGroup}>
        <Button title="Load Ad" onPress={handleLoad} />
        <View style={styles.spacerSmall} />
        <Button title="Show Ad" onPress={handleShow} disabled={!isLoaded} />
      </View>
    </View>
  );
}

Próximas etapas

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