기본 사용법

VPE TV SDK의 기본적인 사용 방법을 안내합니다.

Android TVtvOSFire TV

기본 예제

VpePlayer 컴포넌트를 import하고accessKey와options.playlist를 설정하여 영상을 재생합니다.

import React, { useRef } from 'react';
import { View, StyleSheet } from 'react-native';
import { VpePlayer } from '@sgrsoft/vpe-reactnative-tv-sdk';
import type { PlayerHandle } from '@sgrsoft/vpe-reactnative-tv-sdk';

export default function PlayerScreen() {
    const playerRef = useRef<PlayerHandle>(null);

    return (
        <View style={styles.container}>
            <VpePlayer
                ref={playerRef}
                accessKey="YOUR_ACCESS_KEY"
                options={{
                    playlist: [{
                        file: 'https://example.com/video.m3u8',
                        poster: 'https://example.com/poster.jpg',
                        description: {
                            title: '영상 제목',
                            profile_name: '채널명',
                        },
                    }],
                    autostart: true,
                }}
                onBack={() => {
                    // 뒤로가기 처리 (예: navigation.goBack())
                }}
                onEvent={(event) => {
                    if (event.type === 'ready') {
                        console.log('Player ready');
                    }
                }}
            />
        </View>
    );
}

const styles = StyleSheet.create({
    container: { flex: 1, backgroundColor: '#000' },
});

TV SDK는 네이티브 비디오 엔진(ExoPlayer/AVPlayer)을 사용하여 HLS/DASH를 직접 재생합니다. 별도의 스트리밍 라이브러리 주입이 필요하지 않습니다.

Props (PlayerProps)

Prop	타입	기본값	설명
`accessKey`	string	-	API 접근 키 (필수)
`platform`	'pub' \| 'gov'	'pub'	민간/공공 클라우드
`options`	PlayerOptions	-	플레이어 옵션
`layout`	ControlBarLayout	-	레이아웃 커스터마이징
`onEvent`	(event) => void	-	이벤트 핸들러
`onBack`	() => void	-	뒤로가기 콜백 (TV 전용)
`onExit`	(info) => void	-	종료 시 재생 정보 (TV 전용)
`initialPosition`	number	-	시작 위치 (초, 이어보기용, TV 전용)
`errorOverride`	ReactNode \| Component \| Function	-	커스텀 에러 UI

주의사항

TV SDK에서 사용할 수 없는 코드 패턴을 주의하세요.

// ❌ 존재하지 않는 prop 사용
<VpePlayer src="https://..." />
<VpePlayer videoUrl="https://..." />

// ❌ playlist 없이 file을 직접 전달
<VpePlayer options={{ file: "https://..." }} />

// ❌ 웹 전용 레이아웃 아이템 사용
layout={{ bottom: [{ items: ["FullscreenBtn", "PipBtn"] }] }}

// ✅ 올바른 방법 — 네이티브 엔진이 HLS/DASH를 직접 재생
<VpePlayer options={{ playlist: [{ file: "https://..." }] }} />