고급 네이티브 기능 설정

네이티브 광고는 광고 통합을 맞춤설정할 수 있는 다음과 같은 고급 기능을 제공합니다.

  • 동영상 재생 컨트롤: 동영상 재생 동작을 맞춤설정하고 동영상 수명 주기 이벤트를 수신합니다.
  • AdChoices 아이콘 게재위치: AdChoices 아이콘의 게재위치를 맞춤설정합니다.
  • 맞춤 클릭 동작: 스와이프 동작을 클릭 작업으로 구성합니다.

이 가이드에서는 Google Mobile Ads SDK for React Native를 사용하여 네이티브 광고의 고급 기능을 사용하는 방법을 보여줍니다.

기본 요건

계속하기 전에 다음을 수행하세요.

동영상 재생 및 이벤트 관리

동영상 애셋이 포함된 네이티브 광고를 요청할 때 동영상 재생 시작 옵션을 맞춤설정하고, 동영상 수명 주기 이벤트를 수신 대기하고, 동영상 재생을 제어합니다.

동영상 요청 옵션 구성

초기 동영상 동작을 맞춤설정하려면 VideoOptions 객체를 사용하여 NativeAdRequest 객체에서 videoOptions 속성을 설정합니다.

다음 예에서는 재생이 시작될 때 동영상이 음소거된 상태로 시작되도록 설정합니다.

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

광고가 로드된 후 이 예에서는 광고에 동영상 애셋이 포함되어 있는지 확인하고, 동영상 메타데이터를 로깅하고, 로드된 광고를 반환합니다. 실패하면 예시에서 오류 메시지를 로깅합니다.

가로세로 비율, 현재 시간, 재생 시간과 같은 동영상 메타데이터 속성에 대한 자세한 내용은 MediaContent를 참고하세요.

동영상 이벤트 수신 대기

동영상 시작 또는 종료와 같은 동영상 수명 주기 이벤트를 수신 대기하려면 VideoControllerEventProps 인터페이스의 이벤트 콜백을 NativeAdMediaView 구성요소에 전달합니다.

다음 예에서는 콜백을 전달하여 동영상 수명 주기 이벤트를 로깅하고 동영상 재생을 제어하는 맞춤 버튼을 렌더링합니다.

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

맞춤 컨트롤을 사용 설정하는 경우 NativeAdMediaViewMethods 유형의 ref 속성을 NativeAdMediaView 구성요소에 연결하여 동영상 재생을 제어합니다. NativeAdMediaViewMethods 유형은 VideoControllerMethods 인터페이스의 별칭으로, ref 객체에서 playVideo, pauseVideo, stopVideo, setVideoMuted 메서드를 노출합니다.

AdChoices 게재위치 구성

AdChoices 아이콘의 게재위치를 맞춤설정하려면 AdChoicesPlacement 객체를 사용하여 NativeAdRequest 객체에 adChoicesPlacement 속성을 지정합니다.

다음 예에서는 광고 요청의 왼쪽 상단에 AdChoices 아이콘 게재위치를 구성합니다.

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

이 예시에서는 성공 시 로드된 광고를 반환하고 실패 시 오류 메시지를 로깅합니다.

맞춤 클릭 동작 구성

NativeAdRequest 객체의 customClickGestureDirection 및 customClickGestureAllowTaps 속성을 사용하여 네이티브 광고에서 스와이프 동작을 클릭 작업으로 구성합니다.

다음 예에서는 광고를 로드할 때 동작 방향을 오른쪽 스와이프로 구성하고 탭을 허용합니다.

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

이 예에서는 맞춤 클릭 동작이 사용 설정되어 있는지 확인하고, 성공하면 로드된 광고를 반환하고, 실패하면 오류를 로깅합니다.

광고를 로드한 후 ad.isCustomClickGestureEnabled 속성을 확인하여 해당 광고에 맞춤 클릭 동작이 활성화되어 있는지 확인합니다.

다음 단계

네이티브 광고 고급형 기능을 구성한 후에는 다음에 대해 알아볼 수 있습니다.