Configurar anúncios premiados

Selecione a plataforma: Android iOS Unity Flutter React Native Android (legada)

Os anúncios premiados oferecem aos usuários itens no app em troca de interações com anúncios em vídeo, anúncios jogáveis e pesquisas. Para mais detalhes, consulte Visão geral dos blocos de anúncios premiados.

Para eliminar a latência de apresentação e garantir que um anúncio esteja disponível quando um usuário receber uma recompensa, o Google Mobile Ads SDK for React Native usa o pré-carregamento de anúncios para gerenciar o carregamento em segundo plano, o armazenamento em cache e a reposição do buffer.

Este guia mostra como integrar anúncios premiados em um app nativo do 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/5224354917

iOS

ca-app-pub-3940256099942544/1712485313

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.
• Recarregamento automático: 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 Carregar um único anúncio premiado.

Iniciar pré-carregamento

Para começar a pré-carregar anúncios, chame o método RewardedAdPreloader.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 startRewardedAdPreloader(
  adUnitId: string,
  preloadId: string,
  customPreloadCallback?: PreloadCallback,
): boolean {
  const started = RewardedAdPreloader.start(
    preloadId,
    {
      request: {adUnitId},
      bufferSize: 2,
    },
    {
      // Called when an ad is preloaded into the buffer.
      onAdPreloaded: (event) => {
        console.log(`Rewarded ad preloaded for ${event.preloadId}`);
        customPreloadCallback?.onAdPreloaded?.(event);
      },
      // Called when an ad fails to preload.
      onAdFailedToPreload: (error: LoadAdError) => {
        console.error('Failed to preload rewarded ad:', error.message);
        customPreloadCallback?.onAdFailedToPreload?.(error);
      },
      // Called when all preloaded ads in the buffer have been shown.
      onAdsExhausted: () => {
        console.log('Rewarded ad buffer exhausted.');
        customPreloadCallback?.onAdsExhausted?.();
      },
    },
  );
  return started;
}

Um ID de pré-carregamento é uma string que identifica de forma exclusiva uma configuração de pré-carregamento de anúncios. Se você usar o ID do bloco de anúncios para uma única configuração de pré-carregamento no seu app, poderá usar esse ID 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, Google Mobile Ads SDK for React Native vai invocar o 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 em todos os blocos de anúncios e IDs de pré-carregamento:

• Limite padrão: o Google mantém no máximo seis anúncios pré-carregados na memória. Esse limite é compartilhado entre todos os formatos e IDs de pré-carregamento.
• Tamanho recomendado do buffer: 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 no cache ou destruídos. O pré-carregamento também é pausado temporariamente enquanto um anúncio de tela cheia é exibido na tela.

Sondar e mostrar o anúncio

Antes de mostrar um anúncio, verifique se ele está disponível chamando o método RewardedAdPreloader.isAdAvailable. Para recuperar o anúncio, chame o método RewardedAdPreloader.pollAd.

Para detectar eventos de apresentação, como dispensas de anúncios ou falhas de exibição, defina a propriedade adEventCallback na instância do anúncio antes de chamar o método show:

O exemplo a seguir verifica a disponibilidade do anúncio e detecta eventos de apresentação antes de mostrá-lo:

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

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

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

  ad.show(onRewardEarned);
}

Para liberar memória e recursos, chame o método ad.destroy nos callbacks onAdDismissedFullScreenContent e onAdFailedToShowFullScreenContent.

Ler as informações da resposta

Para inspecionar as informações de resposta do próximo anúncio pré-carregado sem removê-lo do cache, chame o método RewardedAdPreloader.peekAdResponseInfo:

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

Se um anúncio estiver disponível, o método peekAdResponseInfo vai retornar um objeto ResponseInfo com informações sobre a origem do anúncio carregado e os adaptadores de rede.

Opcional: validar callbacks de verificação do lado do servidor

Se o app exigir parâmetros de verificação personalizados, como um ID do usuário ou metadados de recompensa personalizados, em callbacks de verificação do lado do servidor (SSV), defina a propriedade serverSideVerificationOptions na instância do anúncio pesquisado antes de chamar show.

Os valores definidos são transmitidos aos parâmetros de consulta de callback de SSV:

• userId: transmite para o parâmetro de consulta user_id para identificar o usuário.
• customData: transmite para o parâmetro de consulta custom_data para encaminhar metadados personalizados.

O exemplo a seguir define ServerSideVerificationOptions (customData e userId) em um objeto de anúncio premiado antes de mostrar um anúncio:

export function setServerSideVerificationRewarded(ad: RewardedAd) {
  ad.serverSideVerificationOptions = {
    userId: 'user_123',
    customData: 'sample_custom_data',
  };
}

Importante: o valor do parâmetro de consulta custom_data é codificado com escape de porcentagem ou codificado em URL. Ao processar o callback de SSV no seu servidor, decodifique o URL dessa string antes do processamento.

Limpar recursos

Se você não precisar mais mostrar anúncios de um ID de pré-carregamento específico pelo restante da sessão, chame o método RewardedAdPreloader.destroy. Esse processo interrompe o pré-carregamento do ID em questão e libera da memória os anúncios pré-carregados não utilizados.

O exemplo a seguir interrompe o pré-carregamento:

export function destroyRewardedAdPreloader(preloadId: string) {
  RewardedAdPreloader.destroy(preloadId);
}

Depois que o usuário dispensar o anúncio ou se ele não for mostrado, destrua as instâncias individuais de anúncios consultados. 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 premiados pré-carregados:

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

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

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

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

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

Substitua:

• REWARDED_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 premiados, confira os seguintes tópicos:

• Receita de publicidade no nível da impressão
• Privacidade e consentimento do usuário