이벤트

VPE 플레이어에서 발생하는 이벤트를 수신하여 커스텀 로직을 구현할 수 있습니다.

이벤트 리스닝

React에서는 onEvent Props를 사용합니다.

"use client";

import Hls from "hls.js";
import { VpePlayer, type PlayerHandle } from "@sgrsoft/vpe-react-sdk";
import { useRef, useEffect } from "react";

export default function PlayerPage() {
     //이벤트 수신
     const handleEvent = useCallback((evt: any) => {
                switch (evt.type) {
                    case "ready":
                        console.log("ready", "플레이어가 로드되었습니다.");
                        break;
                    case "error":
                        break;
                    case "adStart":
                        console.log("adStart", "광고 시작");
                        break;
                    case "adComplete":
                        console.log("adComplete", "광고 완료");
                        break;
                    case "adSkip":
                        console.log("adSkip", "광고 스킵");
                        break;
                    case "adError":
                        console.log("adError", evt.data?.message);
                        break;
                }
            }, []);

    const playerRef = useRef<PlayerHandle>(null);



    return (
        <VpePlayer
            ref={playerRef}
            hls={Hls}
            accessKey="YOUR_ACCESS_KEY"
            onEvent={handleEvent}
            options={{
                playlist: [{
                    file: "https://example.com/video/master.m3u8",
                }],
            }}
        />
    );
}

재생 이벤트

이벤트설명
ready플레이어가 준비되었을때 발생
play재생이 시작될 때 발생
pause일시정지될 때 발생
ended영상이 끝까지 재생되었을 때 발생
timeupdate재생 시간이 업데이트될 때 주기적으로 발생
seeking탐색(시크)이 시작될 때 발생
seeked탐색(시크)이 완료될 때 발생
ratechange재생 속도가 변경될 때 발생
volumechange볼륨이 변경될 때 발생
loadedmetadata미디어 메타데이터가 로드되었을 때 발생
canplay재생 가능한 상태가 되었을 때 발생

UI 이벤트

이벤트설명
fullscreenchange전체화면 상태가 변경될 때 발생
controlbaractive컨트롤 바가 활성화될 때 발생
controlbarhide컨트롤 바가 숨겨질 때 발생
subtitleChange자막이 켜지거나 변경될 때 발생 — data: { isSubtitle: boolean, subTitleIdx: number }

에러 이벤트

이벤트설명
error재생 에러가 발생했을 때 발생
hlserrorHLS 관련 에러가 발생했을 때 발생
dasherrorDASH 관련 에러가 발생했을 때 발생

광고 이벤트 (IMA)

이벤트설명
adStart광고 재생이 시작될 때 발생
adComplete광고 재생이 완료될 때 발생
adSkip사용자가 광고를 스킵했을 때 발생
adError광고 로드/재생 에러가 발생했을 때 발생

OTT 스킵 이벤트

인트로/오프닝/엔딩 스킵 구간이 스킵되었을 때 발생하는 이벤트입니다. 자세한 설정은 OTT 특화 기능 페이지를 참조하세요.

이벤트설명
introSkip인트로 구간이 스킵되었을 때 발생
openingSkip오프닝 구간이 스킵되었을 때 발생
endingSkip엔딩 구간이 스킵되었을 때 발생

DRM 라이선스 이벤트

DRM 보호 콘텐츠 재생 시 라이선스 요청/응답을 추적할 수 있습니다. HLS(Widevine/PlayReady/FairPlay via hls.js), DASH(Widevine/PlayReady via dash.js), FairPlay native(Safari WebKitMediaKeys) 모두 동일한 통일 스키마로 발화됩니다.

이벤트설명
licenseRequestDRM 라이선스 요청 시작 시 발생
licenseSuccessDRM 라이선스 응답이 성공적으로 수신되었을 때 발생
licenseErrorDRM 라이선스 요청이 실패했을 때 발생
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    hls={Hls}
    dashjs={dashjs}
    options={{ playlist: [{ file: "...", drm: { /* DRM 설정 */ } }] }}
    onEvent={(event) => {
        switch (event.type) {
            case "licenseRequest":
                // { keySystem, url, requestSize, sessionId?, contentId? }
                console.log("DRM 요청:", event.data);
                break;
            case "licenseSuccess":
                // { keySystem, url, status?, durationMs, responseSize?, messageType?, contentId? }
                console.log("DRM 성공:", event.data);
                break;
            case "licenseError":
                // { keySystem, url?, status?, durationMs?, reason: "http"|"network"|"abort"|"key", error?, code? }
                console.warn("DRM 실패:", event.data);
                break;
        }
    }}
/>

페이로드 필드

필드설명
keySystem"com.widevine.alpha" | "com.microsoft.playready" | "com.apple.fps" | "com.apple.fps.1_0" | "unknown"
url라이선스 서버 URL
requestSize요청 페이로드(SPC 등) 바이트 수
responseSize응답 라이선스 바이트 수 (HLS/FairPlay에서 측정, DASH는 registerLicenseResponseFilter로 측정)
durationMs요청 시작 ~ 응답까지 경과 시간
statusHTTP status code
reason실패 원인 (http | network | abort | key)
messageTypeDASH 전용: "license-request" 등 EME 메시지 타입
contentIdFairPlay 전용: SPC를 처리한 contentId

UMD 이벤트 리스닝

<script>
    const player = new ncplayer("player", {
        playlist: [
            { file: "https://example.com/video/master.m3u8" },
        ],
    });

    player.on("play", function() {
        console.log("재생 시작");
    });

    player.on("adStart", function() {
        console.log("광고 시작");
    });

    player.on("adComplete", function() {
        console.log("광고 완료");
    });

    player.on("adSkip", function() {
        console.log("광고 스킵");
    });

    player.on("adError", function(e) {
        console.log("광고 에러", e.data?.message);
    });

    player.on("error", function(e) {
        console.error("에러 발생:", e);
    });
</script>
React
메서드OTT 특화 기능