Impostare le funzionalità native avanzate

Gli annunci nativi offrono le seguenti funzionalità avanzate che ti consentono di personalizzare l'integrazione degli annunci:

  • Controlli di riproduzione video: personalizza il comportamento di riproduzione video e ascolta gli eventi del ciclo di vita del video.
  • Posizionamento dell'icona Scegli Tu!: personalizza il posizionamento dell'icona Scegli Tu!.
  • Gesti di clic personalizzati: configura i gesti di scorrimento come azioni di clic.

Questa guida mostra come utilizzare le funzionalità avanzate degli annunci nativi con Google Mobile Ads SDK for React Native.

Prerequisiti

Prima di continuare, completa queste operazioni:

Gestisci la riproduzione e gli eventi video

Quando richiedi annunci nativi che contengono asset video, personalizza le opzioni di avvio della riproduzione video, ascolta gli eventi del ciclo di vita del video e controlla la riproduzione video.

Configura le opzioni di richiesta video

Per personalizzare il comportamento iniziale del video, imposta la proprietà videoOptions sull'oggetto NativeAdRequest utilizzando un oggetto VideoOptions.

Il seguente esempio imposta il video in modo che l'audio sia disattivato all'inizio della riproduzione:

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

Dopo il caricamento dell'annuncio, questo esempio controlla anche se l'annuncio contiene un asset video, registra i metadati del video e restituisce l'annuncio caricato. In caso di errore, l'esempio registra un messaggio di errore.

Per saperne di più sulle proprietà dei metadati dei video, come le proporzioni, l'ora corrente e la durata, consulta MediaContent.

Ascolta gli eventi video

Per ascoltare gli eventi del ciclo di vita del video, ad esempio quando un video inizia o termina, passa i callback degli eventi dall'interfaccia VideoControllerEventProps al componente NativeAdMediaView.

L'esempio seguente passa i callback per registrare gli eventi del ciclo di vita del video ed esegue il rendering di pulsanti personalizzati per controllare la riproduzione del video:

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 attivi i controlli personalizzati, controlla la riproduzione del video collegando la proprietà ref del tipo NativeAdMediaViewMethods al componente NativeAdMediaView. Il tipo NativeAdMediaViewMethods è un alias dell'interfaccia VideoControllerMethods, che espone i metodi playVideo, pauseVideo, stopVideo e setVideoMuted nell'oggetto ref.

Configura il posizionamento di Scegli Tu!

Per personalizzare il posizionamento dell'icona Scegli Tu!, specifica la proprietà adChoicesPlacement nell'oggetto NativeAdRequest utilizzando l'oggetto AdChoicesPlacement.

L'esempio seguente configura il posizionamento dell'icona Scegli Tu! nell'angolo in alto a sinistra della richiesta di annuncio:

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

Questo esempio restituisce anche l'annuncio caricato in caso di esito positivo e registra un messaggio di errore in caso di esito negativo.

Configura i gesti di clic personalizzati

Configura i gesti di scorrimento come azioni di clic sugli annunci nativi utilizzando le proprietà customClickGestureDirection e customClickGestureAllowTaps nell'oggetto NativeAdRequest.

L'esempio seguente configura la direzione del gesto come scorrimento verso destra e consente i tocchi durante il caricamento di un annuncio:

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

Questo esempio controlla anche se i gesti di clic personalizzati sono attivati, restituisce l'annuncio caricato in caso di esito positivo e registra un errore in caso di esito negativo.

Dopo aver caricato l'annuncio, controlla la proprietà ad.isCustomClickGestureEnabled per verificare se i gesti di clic personalizzati sono attivi per l'annuncio.

Passaggi successivi

Dopo aver configurato le funzionalità avanzate degli annunci nativi avanzati, puoi scoprire di più su quanto segue: