에러 대응

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

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

JS Error 이벤트 안내

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

참고: 에러 코드는 Video Player Enhancement 서비스에서 제공하는 에러 코드 목록으로 전달됩니다.
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// onEvent에 전달되는 error 이벤트 객체 구조:
// {
//     type: "error",
//     state: PlayerStateSnapshot,       // 현재 플레이어 상태
//     prevState?: PlayerStateSnapshot,
//     data: {
//         errorCode: string | null,     // 예: "E0001", "E0004"
//         errorMessage: string | null,  // 에러 설명
//         errorTitle: string | null,    // 에러 제목
//     }
// }

export function App() {
    return (
        <VpePlayer
            accessKey="YOUR_ACCESS_KEY"
            hls={Hls}
            dashjs={dashjs}
            platform="pub"
            options={{
                playlist: [
                    {
                        file: "http://example.com/myVideo.mp4",
                        poster: "http://example.com/myVideoThumb.png",
                    },
                ],
            }}
            onEvent={(event) => {
                if (event.type === "error") {
                    const { errorCode, errorMessage, errorTitle } = event.data;
                    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초 간격
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

export function App() {
    return (
        <VpePlayer
            accessKey="YOUR_ACCESS_KEY"
            hls={Hls}
            dashjs={dashjs}
            platform="pub"
            options={{
                playlist: [
                    {
                        file: "https://dobdd7vj3864.edge.naverncp.com/hls/47NWZgkwsKFkPIU1tix9Zw__/endpoint/sample/example.mp4.smil/master.m3u8",
                        poster: "https://2ardrvaj2252.edge.naverncp.com/endpoint/sample/221027_NAVER_Cloud_intro_Long_ver_01.jpg",
                    },
                ],
                retry: {
                    maxRetry: 10, // 최대 재시도 횟수
                    interval: 5000, // 재시도 횟수 당 지연 시간 (ms)
                },
            }}
        />
    );
}
옵션타입기본값설명
retryObject-재시도 설정
retry.maxRetryInt3다시 시도 횟수
retry.intervalInt5000다시 시도 지연 시간 (ms)

에러 화면 재정의 (override)

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

import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 동영상(MP4)
export function App() {
    return (
        <VpePlayer
            accessKey="YOUR_ACCESS_KEY"
            hls={Hls}
            dashjs={dashjs}
            platform="pub"
            options={{
                playlist: [
                    {
                        file: "https://CDN도메인/example_video_01.mp4",
                        poster: "https://CDN도메인/example_image_01.png",
                    },
                ],
                override: {
                    error(err) {
                        console.log("player error :", err);
                        // 고객사 에러 화면 기능 구현
                    },
                },
            }}
        />
    );
}

에러 UI 커스터마이징 (errorOverride)

errorOverride prop을 사용하면 플레이어 에러 발생 시 기본 에러 UI 대신 커스텀 UI를 렌더링할 수 있습니다.

참고: 유료 티어(isPaidTier)에서만 동작합니다.

타입 정의

errorOverride?: ReactNode | ComponentType<PlayerErrorInfo> | ((info: PlayerErrorInfo) => ReactNode);

type PlayerErrorInfo = {
    errorCode: string | null;
    errorMessage: string | null;
    errorTitle: string | null;
};

1. 렌더 함수 (가장 일반적)

에러 정보를 받아 동적으로 UI를 렌더링합니다. 에러 코드별로 다른 메시지를 표시할 때 유용합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    hls={Hls}
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example.m3u8" }],
    }}
    errorOverride={(info) => (
        <div style={{
            display: "flex",
            width: "100%",
            height: "100%",
            backgroundColor: "#000",
            color: "#fff",
            justifyContent: "center",
            alignItems: "center",
        }}>
            <div>ERROR {info.errorCode}</div>
        </div>
    )}
/>

2. React 컴포넌트

별도의 에러 컴포넌트를 정의하고 전달합니다. PlayerErrorInfo가 props로 전달됩니다.

function CustomError({ errorCode, errorMessage }: PlayerErrorInfo) {
    return <div>에러: {errorCode} - {errorMessage}</div>;
}

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    hls={Hls}
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example.m3u8" }],
    }}
    errorOverride={CustomError}
/>

3. ReactNode (고정 UI)

에러 코드와 관계없이 동일한 고정 UI를 표시합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    hls={Hls}
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example.m3u8" }],
    }}
    errorOverride={<div>재생할 수 없습니다</div>}
/>
errorOverride vs override.error 차이:
  • errorOverride는 VpePlayer props로 전달하며, 에러 발생 시 플레이어 내부에 커스텀 React UI를 직접 렌더링합니다.
  • override.error는 options 내부에 설정하는 콜백 함수로, 에러 정보를 받아 외부 로직(로깅, 별도 DOM 조작 등)을 실행합니다.

에러 코드

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

에러 코드에러 메시지설명
E0001ACCESS DENIED잘못된 접근입니다. 잘못된 옵션 값이 전달되는 경우 발생하며, 동영상 재생 불가
E0002NOT AUTHORIZED동영상을 재생할 권한이 없습니다. 잘못된 요청으로 플레이어 인증이 실패하는 경우 발생
E0003NETWORK ERROR네트워크 연결이 원활하지 않습니다. 네트워크 문제로 플레이어 인증이 실패하는 경우 발생
E0004CANNOT PLAY VIDEO동영상을 재생할 수 없습니다. 영상 재생에 실패하는 경우 발생
E0005LICENSE IS INVALID라이선스가 유효하지 않습니다. 플레이어 라이선스가 만료되었을 때 발생하며, 동영상 재생 불가
E0006LIMIT DENIED월 기본 제공 호출 건수를 초과하였습니다. 무료 플레이어의 월 제공량을 모두 소진한 경우 발생하며, 동영상 재생 불가
Naver Ad Manager SDK 연동레이아웃 시스템