Migration Guide

VPE Player SDK V1 vs V2

v1(ncplayer 순수 JS) 대비 v2(React 기반)에서 새로 추가되거나 의미가 변경된 기능을 정리했습니다.
v1에서 사용하던 대부분의 옵션은 v2에서도 그대로 동작합니다.

핵심 호환성: customBtns만 레이아웃 시스템으로 이관이 필요합니다. 나머지 v1 옵션은 대부분 그대로 재사용 가능합니다.

옵션 변경 요약

신규 / 변경 / 제거된 옵션을 한눈에 확인합니다.

옵션	V1	V2	비고
🆕 ads	—	객체	Google IMA VAST/VMAP 프리롤 광고
🆕 retry	—	Boolean \| { delay, count }	재생 실패 시 자동 재시도
🆕 startTime	—	String \| { startTime, timeInfoText }	예약 재생 + 대기 중 텍스트 커스터마이징
🆕 layout	—	Object	컨트롤바 커스텀 레이아웃 (pc/mobile/fullscreen × live/vod 분기)
🆕 iosFullscreenNativeMode	—	Boolean	iOS 네이티브 풀스크린
🆕 captionType	—	"html" \| "native"	자막 렌더링 방식 선택 — html(커스텀 div) / native(OS 접근성 자막 따라감)
🆕 captionStyle	—	Object	자막 폰트/색상/배경/외곽선/위치 등 PC·모바일 분기 스타일링 (captionType: html 일 때만 적용)

옵션	V1	V2	비고
🔄 override	UI 커스터마이징	이벤트/액션 핸들러 override (error, nextSource, prevSource, pip.on/off)	의미가 확장됨
🔄 icon	문자열(URL)	문자열 \| ReactNode	React 컴포넌트 주입 가능
🔄 objectFit	contain / cover	contain / cover / fill / scale-down / stretch	값 확장
🔄 이벤트 API	DOM 이벤트 리스너	player.on(type, cb) → unsubscribe 함수 반환	구독 해제 / 와일드카드 구독(*) 지원
🔄 description.title / profile_name	문자열	문자열 \| 다국어 객체 ({ ko, en, ja })	다국어 지원
🔄 repeat / loop	repeat	repeat 또는 loop	loop 별칭 추가

항목	V1	V2	대체
🗑 customBtns	배열	—	layout 시스템으로 대체
🗑 src(urlData)	메소드	—	changeOptions({ playlist }) 또는 addNextSource()로 대체
🗑 hlsDestroy() / hlsDestroySet()	메소드	—	destroy() 호출 시 내부 자동 정리

인트로/오프닝/엔딩 스킵, 연령등급, 콘텐츠 경고 등 OTT 서비스에 필요한 기능이 기본 제공됩니다.

기능	옵션 / API	설명
인트로 스킵	playlist[n].intro: { start, duration }	재생 시작 시 스킵 버튼이 표시되는 인트로 구간
오프닝 스킵	playlist[n].opening: { start, duration }	구간 진입 시 자동/수동 스킵
엔딩 스킵	playlist[n].ending: { start, duration }	구간 진입 시 자동/수동 스킵
스킵 이벤트	on("introSkip" \| "openingSkip" \| "endingSkip")	스킵 동작에 대한 이벤트 구독
연령등급 표시	playlist[n].ageRating	"all" / "12" / "15" / "19" — 재생 시작 후 3초간 상단 노출. 다국어(ko/en/ja) 지원
콘텐츠 경고	playlist[n].contentWarnings: string[]	sexuality / violence / language / drugs / horror / imitation / provocative 등

자동 스킵 동작 규칙 — 사용자가 직접 seek 하여 구간 진입 시 자동 스킵은 우회되고, 내부 스킵(인트로 자동 스킵 등)으로 진입 시 자동 스킵이 유지됩니다.

v1의 customBtns() 호출 기반 버튼 추가는 제거되었고, 선언형 레이아웃으로 통합되었습니다.

기능	옵션 / API	설명
반응형 레이아웃	layout: ControlBarLayoutResponsive	pc / mobile / fullscreen 변형을 독립 구성
재생 모드 분기	layout.live / layout.vod	라이브/VOD마다 다른 컨트롤 바 구성
런타임 override	player.layout(next, merge?)	실행 중 레이아웃 덮어쓰기, 체이닝 지원
UI 모드 강제	player.changeUiMode("pc" \| "mobile" \| "fullscreen" \| null)	UI 모드 강제 전환
재생 모드 강제	player.changePlayMode("live" \| "vod" \| null)	재생 모드 강제 전환

API	설명
player.changeOptions(partial)	옵션 부분 갱신 (체이닝 지원)
player.layout(next, merge?)	런타임 레이아웃 override
player.changeUiMode("pc" \| "mobile" \| "fullscreen" \| null)	UI 모드 강제 전환
player.changePlayMode("live" \| "vod" \| null)	재생 모드 강제 전환
player.tokenChange(token)	DRM 토큰 런타임 교체 (시그니처 정리됨)
player.on(type, cb) → unsubscribe	구독 해제 함수 반환 (v1에는 없음)
player.on("*", cb)	와일드카드 구독 (모든 이벤트)
player.addNextSource(src) / addPrevSource(src)	동적 소스 추가 (체이닝 지원)

기능	설명
<VpePlayer />	React 컴포넌트 (forwardRef + PlayerHandle)
scopeId	페이지 내 다중 플레이어의 독립 동작을 보장하는 스코프 식별자
playerControllerRegistry	스코프별 컨트롤러, 이벤트 리스너, UI 가시성 핸들러 관리
PlayerEventBridge	스코프별 이벤트 버스
ES 모듈 빌드	import { VpePlayer, setup, Ncplayer } from "@sgrsoft/vpe-react-sdk"

항목	V1	V2
extra.duration / contentDuration	일부 보고에서 0 또는 누락	모든 보고에 최신값 포함
extra.percent / watch_percent	일부 보고에만 존재	모든 보고에 현재 재생율 포함
extra.url / type / videoFormat / poster / title / metaData / video_type	누락 가능	모든 보고에 포함
세션 종료 beacon	beforeunload 단편 지원	beforeunload + visibilitychange 기반 navigator.sendBeacon
OTT / 광고 이벤트 통계	없음	스킵/광고 이벤트 MA 반영

기능	설명
Vite 기반 빌드	ES + UMD 2가지 포맷 (VPE_BUILD_FORMAT=es \| umd 환경변수로 선택)
로컬 모노레포 개발	VPE_LOCAL_SDK=true로 core-sdk / react-ui 로컬 참조
React 18/19 peer 지원	peerDependencies에 React 18.x / 19.x
hls.js / dashjs 외부 주입	번들에 미포함, props 주입 또는 window 전역 참조