---
title: "기본 사용법"
slug: "vpe-tv-getting-started"
updated: 2026-09-17T09:08:03Z
published: 2026-09-17T09:08:03Z
canonical: "guide.ncloud-docs.com/vpe-tv-getting-started"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 기본 사용법

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

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

## 기본 예제

`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)

`VpePlayer` 컴포넌트가 지원하는 prop은 다음과 같습니다.

| 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://..." }] }} />
```