에러 대응

Classic/VPC 환경에서 이용 가능합니다. 에러 대응에서는 스크립트 코드를 수정하여 Error 이벤트를 통해 재생 소스에 사용자 정의 메시지를 적용하는 방법을 설명합니다.

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

JS Error 이벤트 안내

플레이어를 호출하는 함수에서 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;
    }
});

에러 시 Retry 환경 설정

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

참고:

플레이어 초기화 시 영상 재생 시도 추가: 기본값 최대 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	Int	3	다시 시도 횟수
retry.interval	Int	5000	다시 시도 지연 시간 (ms)

에러 화면 재정의 (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>
    <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>