Definir recursos nativos avançados

Os anúncios nativos oferecem os seguintes recursos avançados que permitem personalizar a integração de anúncios:

  • Controles de mídia: personalize o comportamento de reprodução de vídeo e ouça eventos de ciclo de vida de vídeo.
  • Posicionamento do ícone Opções de Anúncios: personalize o posicionamento do ícone Opções de Anúncios.
  • Gestos de clique personalizados: configure gestos de deslizar como ações de clique.

Este guia mostra como usar os recursos avançados dos anúncios nativos com o Google Mobile Ads SDK for React Native.

Pré-requisitos

Antes de continuar, faça o seguinte:

Gerenciar a reprodução e os eventos de vídeo

Ao solicitar anúncios nativos que contêm recursos de vídeo, personalize as opções de inicialização da reprodução de vídeo, detecte eventos do ciclo de vida do vídeo e controle a reprodução de vídeo.

Configurar opções de solicitação de vídeo

Para personalizar o comportamento inicial do vídeo, defina a propriedade videoOptions no objeto NativeAdRequest usando um objeto VideoOptions.

O exemplo a seguir define o vídeo para iniciar sem som quando a reprodução começa:

export async function loadNativeVideoAd(
  adUnitId: string,
): Promise<NativeAd | null> {
  try {
    const ad = await NativeAd.load({
      adUnitId,
      videoOptions: {
        // Autoplay video with sound muted.
        startMuted: true,
      },
    });

    // Inspect video metadata if the ad contains video content.
    if (ad.mediaContent.hasVideoContent) {
      console.log('Video duration in seconds:', ad.mediaContent.duration);
      console.log('Video aspect ratio:', ad.mediaContent.aspectRatio);
    }

    return ad;
  } catch (error) {
    const loadError = error as LoadAdError;
    console.error('Failed to load native video ad:', loadError.message);
    return null;
  }
}

Depois que o anúncio é carregado, esse exemplo também verifica se ele contém um recurso de vídeo, registra os metadados do vídeo e retorna o anúncio carregado. Em caso de falha, o exemplo registra uma mensagem de erro.

Para mais informações sobre as propriedades de metadados de vídeo, como proporção, tempo atual e duração, consulte MediaContent.

Detectar eventos de vídeo

Para detectar eventos de ciclo de vida do vídeo, como quando um vídeo começa ou termina, transmita callbacks de evento da interface VideoControllerEventProps para o componente NativeAdMediaView.

O exemplo a seguir transmite callbacks para registrar eventos de ciclo de vida do vídeo e renderiza botões personalizados para controlar a reprodução de vídeo:

export function NativeAdWithVideoControls({ad}: {ad: NativeAd}) {
  const mediaViewRef = useRef<NativeAdMediaViewMethods>(null);

  return (
    <NativeAdView ad={ad}>
      {/* Video lifecycle callbacks */}
      <NativeAdMediaView
        ref={mediaViewRef}
        // Called when video playback starts.
        onVideoStart={() => {
          console.log('Video playback started.');
        }}
        // Called when video playback resumes or plays.
        onVideoPlay={() => {
          console.log('Video is playing.');
        }}
        // Called when video playback pauses.
        onVideoPause={() => {
          console.log('Video playback paused.');
        }}
        // Called when video playback completes.
        onVideoEnd={() => {
          console.log('Video playback finished.');
        }}
        // Called when the video mute state changes.
        onVideoMute={(isMuted: boolean) => {
          console.log(`Video mute state changed: ${isMuted}`);
        }}
      />

      {/* Custom playback controls (Ad Manager customControlsRequested only) */}
      <View>
        {/* Plays or resumes the video. */}
        <Button
          title="Play"
          onPress={() => mediaViewRef.current?.playVideo()}
        />
        {/* Pauses video playback. */}
        <Button
          title="Pause"
          onPress={() => mediaViewRef.current?.pauseVideo()}
        />
        {/* Stops video playback and resets the playback position to the beginning. */}
        <Button
          title="Stop"
          onPress={() => mediaViewRef.current?.stopVideo()}
        />
        {/* Mutes or unmutes audio. */}
        <Button
          title="Mute"
          onPress={() => mediaViewRef.current?.setVideoMuted(true)}
        />
        <Button
          title="Unmute"
          onPress={() => mediaViewRef.current?.setVideoMuted(false)}
        />
      </View>
    </NativeAdView>
  );
}

Quando você ativa os controles personalizados, controla a reprodução de vídeo anexando a propriedade ref do tipo NativeAdMediaViewMethods ao componente NativeAdMediaView. O tipo NativeAdMediaViewMethods cria um alias para a interface VideoControllerMethods, que expõe os métodos playVideo, pauseVideo, stopVideo e setVideoMuted no objeto ref.

Configurar a posição das Opções de Anúncios

Para personalizar o posicionamento do ícone Opções de Anúncios, especifique a propriedade adChoicesPlacement no objeto NativeAdRequest usando o objeto AdChoicesPlacement.

O exemplo a seguir configura o posicionamento do ícone Opções de Anúncios no canto superior esquerdo da solicitação de anúncio:

export async function loadNativeAdWithAdChoicesPlacement(
  adUnitId: string,
): Promise<NativeAd | null> {
  try {
    const ad = await NativeAd.load({
      adUnitId,
      // Render the AdChoices icon in the top-left corner.
      adChoicesPlacement: AdChoicesPlacement.TOP_LEFT,
    });
    return ad;
  } catch (error) {
    const loadError = error as LoadAdError;
    console.error('Failed to load native ad:', loadError.message);
    return null;
  }
}

Esse exemplo também retorna o anúncio carregado em caso de sucesso e registra uma mensagem de erro em caso de falha.

Configurar gestos de clique personalizados

Configure gestos de deslizar como ações de clique em anúncios nativos usando as propriedades customClickGestureDirection e customClickGestureAllowTaps no objeto NativeAdRequest.

O exemplo a seguir configura a direção do gesto como um deslizar para a direita e permite toques ao carregar um anúncio:

export async function loadNativeAdWithCustomClick(
  adUnitId: string,
): Promise<NativeAd | null> {
  try {
    const ad = await NativeAd.load({
      adUnitId,
      // Require a right swipe gesture for clicks while allowing standard taps.
      customClickGestureDirection: SwipeGestureDirection.RIGHT,
      customClickGestureAllowTaps: true,
    });

    if (ad.isCustomClickGestureEnabled) {
      console.log('Custom click gestures are enabled for this ad.');
    }

    return ad;
  } catch (error) {
    const loadError = error as LoadAdError;
    console.error('Failed to load native ad:', loadError.message);
    return null;
  }
}

Este exemplo também verifica se os gestos de clique personalizados estão ativados, retorna o anúncio carregado em caso de sucesso e registra um erro em caso de falha.

Depois de carregar o anúncio, verifique a propriedade ad.isCustomClickGestureEnabled para conferir se os gestos de clique personalizados estão ativos para esse anúncio.

Próximas etapas

Depois de configurar os recursos avançados de anúncios nativos, saiba mais sobre o seguinte: