YouTube Player API를 통한 유튜브 영상 제어

YouTube Player API는 웹사이트에서 YouTube 동영상을 임베드하고 JavaScript로 제어할 수 있는 API입니다. 이 API를 사용해 동영상 재생, 일시정지 등의 기능으로 플레이어를 제어하고, 플레이어의 행동을 추적할 수 있습니다.

이번 포스팅에서는 Iframe Player API를 활용해 동영상의 재생상태를 감지하거나, 동영상 플레이어의 이벤트를 식별하고 이벤트리스너로 응답하는 과정에 대해 알아보도록 하겠습니다.

Iframe이란

먼저 YouTube Player API에 대해 알아보기 전에 Iframe라는 개념을 알면 좋을 것 같습니다.

Iframe은 HTML에서 다른 웹 페이지나 콘텐츠를 현재 페이지에 삽입할 수 있는 요소입니다. 즉, Iframe을 사용하면 현재 웹 페이지 안에 별도의 독립적인 콘텐츠를 포함할 수 있습니다. 특히 YouTube 동영상을 임베드하거나 외부 콘텐츠를 표시할 때 자주 사용됩니다.

아래 YouTube 동영상 URL을 입력해 동영상을 임베드 해보세요.
예시) https://www.youtube.com/watch?v=K7bdDwRw60o

YouTube URL을 입력하세요

YouTube Iframe API 시작하기

1. YouTube Iframe API 스크립트 로드

<script src="https://www.youtube.com/iframe_api"></script>

이 URL에 있는 스크립트는 YouTube에서 제공하는 Iframe API의 JavaScript 파일입니다.
HTML에 직접 스크립트를 추가할 수도 있고, JavaScript를 이용해 동적으로 추가할 수도 있습니다.
API 스크립트가 로드되면 onYouTubeIframeAPIReady 함수가 자동으로 호출됩니다.

2. onYouTubeIframeAPIReady 함수 호출

<script>
  let player;

  function onYouTubeIframeAPIReady() {
    player = new YT.Player('player', {
      height: '360',
      width: '640',
      videoId: '0V1JnS7mamU',
      playerVars: {
        autoplay: true,
        loop: false,
        playlist: '0V1JnS7mamU',
      },
      events: {
        'onReady': onPlayerReady,
        'onStateChange': onPlayerStateChange,
      },
    });
  }
</script>

API 코드가 로드되면 onYouTubeIframeAPIReady 함수가 호출되며, 이 시점에서 YouTube 동영상 플레이어 객체를 초기화할 수 있습니다. 플레이어가 초기화되면 웹 페이지에 영상이 Iframe의 형태로 삽입됩니다.
이 함수명은 수정할 수 없습니다. 정확히 동일한 이름을 사용해야 합니다.

3. 이벤트 리스너 설정

<script>
  function onPlayerReady(event) { 
    event.target.playVideo();
    event.target.mute();
  }

  function onPlayerStateChange(event) {
    if (event.data == YT.PlayerState.ENDED) {
      console.log("onPlayerStateChange:",event.data,"ENDED");
    } else if (event.data == YT.PlayerState.PLAYING) {
      console.log("onPlayerStateChange:",event.data,"PLAYING");
    } else if (event.data == YT.PlayerState.PAUSED) {
      console.log("onPlayerStateChange:",event.data,"PAUSED");
    } else if (event.data == YT.PlayerState.BUFFERING) {
      console.log("onPlayerStateChange:",event.data,"BUFFERING");
    } else if (event.data == YT.PlayerState.CUED) {
      console.log("onPlayerStateChange:",event.data,"CUED");
    }
  }
</script>

YouTube IFrame API에서는 동영상의 상태 변화(PLAYING, PAUSED, ENDED 등)를 감지하고, 이 변화에 따라 원하는 작업을 수행하기 위해 이벤트 리스너를 설정합니다.

이벤트 리스너란?
이벤트 리스너(Event Listener)는 특정 이벤트가 발생했을 때 자동으로 실행될 함수를 등록하는 기능입니다.
예를 들어, 사용자가 동영상을 재생하면 PLAYING 이벤트가 발생합니다. 이때, 등록된 이벤트 리스너가 호출되어, 동영상의 남은 시간을 계산하거나 사용자에게 알림을 표시할 수 있습니다.

이벤트 리스너를 활용한 동영상 제어 및 후속 작업

1. 영상 재생 시 카운트다운 실행

<script>
  let countdown;

  function onPlayerStateChange(event) {
    if (event.data === YT.PlayerState.ENDED) {
      console.log("onPlayerStateChange:", event.data, "ENDED");
      clearInterval(countdown);
      document.querySelector('.btn_count').textContent = '0';
    } else if (event.data === YT.PlayerState.PLAYING) {
      console.log("onPlayerStateChange:", event.data, "PLAYING");
      const duration = player.getDuration();
      startCountdown(duration);
    }
  }

  function startCountdown(duration) {
    const btnCount = document.querySelector('.btn_count');
    clearInterval(countdown);

    countdown = setInterval(() => {
      const currentTime = player.getCurrentTime();
      const remainingTime = Math.floor(duration - currentTime);

      btnCount.textContent = remainingTime;

      if (remainingTime <= 0) {
        clearInterval(countdown);
      }
    }, 1000);
  }
</script>

• startCountdown() 함수는 동영상 재생 시간(duration)을 기준으로 남은 시간을 계산하고 1초마다 업데이트합니다.
• setInterval()을 사용해 1초마다 남은 시간을 계산하고, 화면에 표시합니다.
• 동영상이 종료되거나 시간이 0이 되면, clearInterval()을 호출하여 카운트다운을 멈춥니다.
• 동영상 재생 버튼을 클릭하면, 남은 시간이 화면에 표시되며, 사용자는 동영상 종료까지 남은 시간을 확인할 수 있습니다.

2. 영상 종료 시 Postback 요청

<script>
  function onPlayerStateChange(event) {
    if (event.data === YT.PlayerState.ENDED) {
      console.log("onPlayerStateChange:", event.data, "ENDED");
      endEvent('ad123', 'creative456', 'user789');
    }
  }

  function endEvent(adId, creativeId, userId) {
    const watchAlerts = document.querySelectorAll('.watch_alert');

    // Postback 요청
    fetch('/video-complete', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        adId: adId,
        creativeId: creativeId,
        userId: userId,
      }),
    })
      .then((response) => {
        if (response.ok) {
          console.log('Postback success');
          watchAlerts.forEach((alert) => alert.classList.add('success'));
        } else {
          console.error('Postback fail');
        }
      })
      .catch((error) => console.error('Fetch error:', error));
  }
</script>

• 동영상이 종료되면, endEvent() 함수가 호출되어 서버로 Postback 요청을 전송합니다.
• fetch()를 사용해 POST 요청을 보내며, 동영상의 시청 완료 데이터를 서버로 전송합니다.
• 요청이 성공하면, 화면에 알림(.watch_alert)이 표시되고, 실패하면 콘솔에 에러 메시지를 출력합니다.
• 동영상 시청이 완료되면, 서버로 시청 기록이 전송되고, 이 데이터를 통해 분석이 가능합니다.

아래 YouTube 동영상 URL을 입력해 동영상을 임베드 해보세요.
자동 재생, 타이머 기능, 종료 시 알림 기능도 함께 확인해보세요.
예시) https://www.youtube.com/watch?v=K7bdDwRw60o

반복 재생 설정 시 주의할 점

• YouTube Iframe API를 사용하여 반복 재생 기능을 구현할 때, 주의할 사항이 있습니다. 반복적인 재생 테스트를 진행하다 보면, YouTube에서 비정상적인 활동으로 감지되어 봇으로 인식될 수 있습니다.
• 동영상 재생이 차단되며, 더 이상 동영상이 로드되지 않고, "동영상을 재생할 수 없음" 오류가 발생할 수 있습니다.
• 개발 환경에서는 반복 재생(loop) 기능을 비활성화하고 테스트를 진행하는 것이 좋습니다.

지금까지 Youtube Iframe API에 대해 알아보았습니다. Iframe API를 사용하면 간편하게 동영상을 임베드 할 수 있고, JavaScript를 통해 동영상을 제어하거나 다양한 이벤트를 감지할 수 있습니다. 이를 통해 보다 나은 사용자 경험을 제공하고, 분석 데이터를 손쉽게 수집할 수 있습니다

Ref.
YouTube Player API 참조 문서