에러 대응

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

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

에러 이벤트 감지

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

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: "https://example.com/myVideo.mp4",
            poster: "https://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;
          }
        }
      }}
    />
  );
}

재시도 설정

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

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

에러 화면 재정의

기본으로 제공되는 에러 화면을 고객사가 원하는 코드로 변경하여 실행할 수 있습니다. 에러 화면을 재정의(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);
            // 고객사 에러 화면 기능 구현
          },
        },
      }}
    />
  );
}

에러 화면 커스터마이징

타입 정의

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

에러 코드

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