에러 대응

Classic/VPC 환경에서 이용 가능합니다.

재생 중 발생하는 에러를 감지하고 처리하는 방법을 설명합니다.

참고

Video Player Enhancement 서비스와 함께 Media Analytics 서비스를 이용하면 Media Analytics 관리 페이지에서 에러 코드를 손쉽게 확인할 수 있습니다.

에러 이벤트 감지

플레이어를 호출하는 함수에서 player.on("error", (err) => {}) 코드로 이벤트를 감지하여 에러 코드와 메시지를 호출할 수 있습니다.

참고

에러 코드는 Video Player Enhancement 서비스에서 제공하는 에러 코드 목록으로 전달됩니다.

const player = new ncplayer("video", {
  playlist: [
    {
      file: "http://example.com/myVideo.mp4",
      poster: "http://example.com/myVideoThumb.png",
    },
  ],
});

// error 이벤트 데이터 구조:
// {
//   errorCode: string | null,     // 예: "E0001", "E0004"
//   errorMessage: string | null,  // 에러 설명
//   errorTitle: string | null,    // 에러 제목
// }

player.on("error", function(err) {
  var errorCode = err.errorCode;
  var errorMessage = err.errorMessage;
  var errorTitle = err.errorTitle;

  switch (errorCode) {
    case "E0001":
      console.log("E0001 - ACCESS DENIED");
      console.log(errorTitle, errorMessage);
      break;
    case "E0002":
      console.log("E0002 - NOT AUTHORIZED");
      console.log(errorTitle, errorMessage);
      break;
    case "E0003":
      console.log("E0003 - NETWORK ERROR");
      console.log(errorTitle, errorMessage);
      break;
    case "E0004":
      console.log("E0004 - CANNOT PLAY");
      console.log(errorTitle, errorMessage);
      break;
    case "E0005":
      console.log("E0005 - LICENSE IS INVALID");
      console.log(errorTitle, errorMessage);
      break;
    case "E0006":
      console.log("E0006 - LIMIT DENIED");
      console.log(errorTitle, errorMessage);
      break;
    default:
      break;
  }
});

재시도 설정

플레이어가 오류를 응답하기 전 최대 재시도 횟수 및 최대 지연 시간 설정을 커스터마이징할 수 있습니다.

참고

플레이어 초기화 시 영상 재생 시도 추가: 기본값 최대 3회, 5초 간격
Live/VOD가 중단되었을 때 재생 시도 추가: 기본값 최대 3회, 5초 간격

const player = new ncplayer("video", {
  playlist: [
    {
      file: "https://CDN도메인/example.m3u8",
      poster: "https://CDN도메인/poster.jpg",
    },
  ],
  retry: {
    maxRetry: 10,   // 최대 재시도 횟수
    interval: 5000, // 재시도 횟수당 지연 시간(ms)
  },
});

옵션	타입	기본값	설명
`retry`	Object	-	재시도 설정
`retry.maxRetry`	Integer	`3`	최대 재시도 횟수
`retry.interval`	Integer	`5000`	재시도 지연 시간 (밀리초)

에러 화면 재정의

기본으로 제공되는 에러 화면을 고객사가 원하는 코드로 변경하여 실행할 수 있습니다. 에러 화면을 재정의(override)하면 마지막 재생 위치에서 정지(pause) 상태를 유지한 채 플레이어 오버레이를 통해 에러 화면을 구현할 수 있습니다.

// 동영상(MP4)
const player = new ncplayer("video", {
  playlist: [
    {
      file: "https://CDN도메인/example_video_01.mp4",
      poster: "https://CDN도메인/example_image_01.png",
    },
  ],
  override: {
    error: function(err) {
      console.log("player error:", err);

      // 고객사 에러 화면 기능 구현
      // 예: document.getElementById("error-overlay").style.display = "block";
    },
  },
});

에러 코드

Video Player Enhancement 서비스에서 제공하는 에러 코드 목록은 다음과 같습니다.

에러 코드	에러 메시지	설명
E0001	ACCESS DENIED	잘못된 접근. 잘못된 옵션 값이 전달되어 동영상 재생 불가
E0002	NOT AUTHORIZED	동영상을 재생할 권한이 없음. 잘못된 요청으로 플레이어 인증 실패
E0003	NETWORK ERROR	네트워크 연결이 원활하지 않음. 네트워크 문제로 플레이어 인증 실패
E0004	CANNOT PLAY VIDEO	동영상을 재생할 수 없음. 영상 재생 실패
E0005	LICENSE IS INVALID	라이선스가 유효하지 않음. 플레이어 라이선스가 만료되어 동영상 재생 불가
E0006	LIMIT DENIED	월 기본 제공 호출 건수를 초과. 무료 플레이어의 월 제공량을 모두 소진하여 동영상 재생 불가

전체 HTML 예제

<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>VPE Player - 에러 대응</title>

  <!-- hls.js / dash.js를 VPE 스크립트보다 먼저 로드 -->
  <script src="https://player.vpe.naverncp.com/lib/js/hls.min.js"></script>
  <script src="https://player.vpe.naverncp.com/lib/js/dash.all.min.js"></script>
  <script src="https://player.vpe.naverncp.com/v2/ncplayer.js?access_key=YOUR_ACCESS_KEY"></script>
</head>
<body>
  <div id="video" style="max-width: 800px; margin: 0 auto;"></div>

  <div id="error-overlay" style="display:none; color:red; text-align:center; padding:20px;">
    <h2>재생 오류가 발생했습니다</h2>
    <p id="error-detail"></p>
  </div>

  <script>
    const player = new ncplayer("video", {
      playlist: [
        {
          file: "https://CDN도메인/example_video_01.mp4",
          poster: "https://CDN도메인/poster.jpg",
        },
      ],
      retry: {
        maxRetry: 5,
        interval: 3000,
      },
      override: {
        error: function(err) {
          document.getElementById("error-overlay").style.display = "block";
          document.getElementById("error-detail").textContent =
            err.errorCode + " - " + err.errorMessage;
        },
      },
    });

    player.on("error", function(err) {
      console.log("에러 발생:", err.errorCode, err.errorMessage);
    });
  </script>
</body>
</html>