Configurar anúncios intersticiais premiados

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

Os anúncios intersticiais premiados são um formato de tela cheia que permite oferecer itens no app em troca de anúncios que aparecem entre telas ou níveis de jogos. Diferente dos anúncios premiados, os usuários não precisam ativar a visualização do anúncio. Para mais detalhes, consulte Estudos de caso da AdMob e Visão geral dos blocos de anúncios intersticiais premiados (Beta).

Para eliminar a latência de apresentação e garantir que um anúncio esteja disponível quando uma transição ocorrer, 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 o reabastecimento do buffer.

Este guia mostra como integrar anúncios intersticiais premiados com pré-carregamento de anúncios em um app nativo 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/5354046379

iOS

ca-app-pub-3940256099942544/6978759866

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 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 intersticial premiado.

Iniciar pré-carregamento

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

preloadId é uma string que identifica exclusivamente uma configuração de pré-carregamento de anúncios. Se você usa um ID do bloco de anúncios para uma única configuração de pré-carregamento no seu app, use 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, 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. Esse limite é compartilhado entre todos os formatos e IDs de pré-carregamento.
• Buffer recomendado: dois anúncios pré-carregados 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 RewardedInterstitialAdPreloader.isAdAvailable. Para recuperar o anúncio, chame o método RewardedInterstitialAdPreloader.pollAd.

Para mostrar um anúncio, chame o método show com um callback onUserEarnedReward para conceder a recompensa quando o usuário terminar de assistir o anúncio. 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 em tela cheia antes de mostrar o anúncio:

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

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

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

export function peekRewardedInterstitialAdResponseInfo(
  preloadId: string,
): ResponseInfo | null {
  const responseInfo =
    RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo) {
    console.log(
      'Next preloaded rewarded interstitial 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 SSV

Se o app precisar de 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, na sigla em inglês), defina a propriedade serverSideVerificationOptions na instância do anúncio pesquisado antes de chamar o método 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 intersticial premiado antes de mostrar um anúncio:

export function setServerSideVerificationRewardedInterstitial(
  ad: RewardedInterstitialAd,
) {
  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 RewardedInterstitialAdPreloader.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 destroyRewardedInterstitialAdPreloader(preloadId: string) {
  RewardedInterstitialAdPreloader.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

Esta seção aborda a implementação completa do pré-carregamento de anúncios.

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

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

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

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

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

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

Próximas etapas

Depois de integrar os anúncios intersticiais premiados, confira os seguintes tópicos:

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