---
title: "VPE 2.0 React Native 사용 준비"
slug: "vpe-v2-react-native-spec"
updated: 2026-09-17T09:08:03Z
published: 2026-09-17T09:08:03Z
canonical: "guide.ncloud-docs.com/vpe-v2-react-native-spec"
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.

# VPE 2.0 React Native 사용 준비

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

VPE React Native SDK를 설치하고 프로젝트를 설정하는 방법을 안내합니다.

## 지원 환경

VPE React Native SDK는 Expo 및 React Native 환경에서 사용할 수 있습니다. React Native Video 라이브러리 V6.x 기반으로 동작하며, `react-native >= 0.68.2` 환경이 필요합니다.

참고

VPE RN SDK는 네이티브 브릿지를 사용하는 영역이 있어 Expo GO에서는 테스트를 지원하지 않습니다. Development build를 사용해 주시기 바랍니다.

## 설치 및 초기 설정

### npm 설치

```
npm install vpe-react-native
```

### 의존성 설치

```
npm install @sgrsoft/react-native-video react-native-svg react-native-capture-protection phosphor-react-native
```

### iOS 사전 설정

참고

Expo로 빌드하는 경우, 이 단계는 필요하지 않습니다.

```
cd ios && pod install
```

### 개발용 테스트 키 및 테스트용 AppId 설정

Video Player Enhancement는 AppId + AccessKey 조합으로 라이선스 체크를 실시합니다. Expo GO에서는 정식 AppId를 이용할 수 없어 개발 모드 전용 props가 존재합니다.

```
<VpePlayer
  devTestAppId={'TEST DEV AppID'} // Expo GO 대응, 개발 모드에서만 사용됨
  accessKey={'VPE ACCESS KEY'}    // AppId와 일치하는 Access Key
/>
```

### app.json 설정

`plugins` 항목 및 Picture-in-Picture, Background play 지원을 위한 옵션을 추가해야 합니다.

```
{
  "expo": {
    "plugins": [
      [
        "react-native-capture-protection",
        {
          "captureType": "fullMediaCapture"
        }
      ],
      [
        "@sgrsoft/react-native-video",
        {
          "enableAndroidPictureInPicture": true,
          "enableNotificationControls": true
        }
      ]
    ],
    "ios": {
      "infoPlist": {
        "UIBackgroundModes": ["audio", "fetch"]
      }
    },
    "android": {
      "edgeToEdgeEnabled": true,
      "supportsPictureInPicture": true,
      "permissions": [
        "android.permission.FOREGROUND_SERVICE"
      ]
    }
  }
}
```

## Props

플레이어를 구성하는 데 사용할 수 있는 속성 목록을 보여줍니다.

### devTestAppId

`Android` `iOS`

VPE는 앱 아이디 기반 라이선스가 설정됩니다. 개발 환경에서 앱 아이디를 개발 전용으로 설정하여 작업이 가능하도록 도움을 주는 속성입니다.

```
<VpePlayer
  devTestAppId={'TEST DEV AppID'} // Expo GO 대응, 개발 모드에서만 사용됨
/>
```

### accessKey

`Android` `iOS`

VPE 라이선스키를 설정합니다.

```
<VpePlayer
  accessKey={'VPE ACCESS KEY'} // AppId와 일치하는 Access Key
/>
```

### platform

`Android` `iOS`

VPE React Native SDK는 민간(`pub`), 공공(`gov`) 환경을 지원합니다. 기본값은 민간(`pub`)입니다.

```
<VpePlayer
  platform={'pub'} // pub: 민간, gov: 공공
/>
```

## Events

`Android` `iOS`

VPE React Native SDK에서 플레이어 이벤트를 바인딩하는 기능을 제공합니다.

```
<VpePlayer
  events={{
    ready: () => {
      console.log('player ready');
    },
    fullScreen: (data) => {
      setIsFullScreen(data.isFullScreen);
    },
    timeupdate: (data) => {
      console.log('영상 전체 길이 (duration) : ', data.duration);
      console.log('현재 재생 위치 (currentTime) : ', data.currentTime);
      console.log('현재 재생 퍼센트 (percent) : ', data.percent);
      console.log('누적 재생 시간 (viewingTime) : ', data.viewingTime);
      console.log('재생소스 타입 (sourceType) : ', data.sourceType);
    },
    nextTrack: (data) => { console.log(data); },
    prevTrack: (data) => { console.log(data); },
    volumechange: (data) => { console.log(data); },
    play: () => { console.log('play'); },
    pause: () => { console.log('pause'); },
    ended: () => { console.log('ended'); },
    controlbarActive: () => { console.log('controlbarActive'); },
    controlbarDeactive: () => { console.log('controlbarDeactive'); },
    error: (data) => { console.log('error', data); },
  }}
/>
```

| 이벤트 | 설명 | 리턴값 |
| --- | --- | --- |
| ready | 플레이어 로드 완료 | - |
| fullScreen | 전체화면 실행 | `data.isFullScreen` (true/false) |
| timeupdate | 재생 | duration, currentTime, percent, viewingTime, sourceType |
| nextTrack | 다음 영상으로 이동 | 다음 영상 source |
| prevTrack | 이전 영상으로 이동 | 이전 영상 source |
| volumechange | 플레이어 볼륨 변경 | 음소거 여부 |
| play | 재생 시작 | - |
| pause | 정지 실행 | - |
| ended | 현재 영상 재생 완료 | - |
| controlbarActive | 컨트롤 UI 활성화 | - |
| controlbarDeactive | 컨트롤 UI 비활성화 | - |
| backPress | BackBtn 클릭 시 호출. 네비게이션 처리는 사용자 책임 | - |
| seeking/seeked | 탐색 시작/완료 | currentTime |
| error | 플레이어에 에러 발생 | error_code, error_message |

## Options

`Android` `iOS`

VPE 플레이어 옵션을 설정합니다. 플레이어 옵션은 별도의 페이지에서 상세히 설명합니다.

```
<VpePlayer
  options={{
    playlist: [
      {
        file: 'https://example.com/video/master.m3u8',
      },
    ],
    autostart: true,
    muted: true,
    aspectRatio: '16/9',
  }}
/>
```

### events.backPress (뒤로가기)

`Android` `iOS`

Breaking change: 기존 `props.backButton`은 폐지되었습니다. 대신 레이아웃에 `BackBtn` 컨트롤을 배치하고, 콜백은 `events.backPress`로 전달합니다. 네비게이션 처리(예: `navigation.goBack()`)는 사용자 책임입니다.

```
<VpePlayer
  events={{
    backPress: () => {
      navigation.goBack();
    },
  }}
/>
```

### options.icon (커스텀 아이콘)

참고

**Breaking change**: 기존 props.icon은 options.icon으로 이동했습니다. 자세한 사용법은 [커스텀 아이콘](https://developer.vpe.naverncp.com/docs/rn/custom-icon) 문서를 참고하세요.

## Layout

`Android` `iOS`

ControlBar의 컨트롤 배치, 그룹, 환경별 구성을 선언적으로 정의합니다. 자세한 내용은 [레이아웃 시스템](https://developer.vpe.naverncp.com/docs/rn/layout-system) 문서를 참고해 주십시오.

```
<VpePlayer
  layout={{
    pc:         { vod: { /* ... */ }, live: { /* ... */ } },
    mobile:     { vod: { /* ... */ }, live: { /* ... */ } },
    fullscreen: { vod: { /* ... */ }, live: { /* ... */ } },
    breakpoint: 768,
  }}
/>
```

## Override

`Android` `iOS`

VPE 플레이어의 기본 기능을 직접 오버라이드하여 원하는 기능을 구현할 수 있습니다.

```
<VpePlayer
  override={{
    nextSource: () => {
      Alert.alert('nextSource');
    },
    prevSource: () => {
      Alert.alert('prevSource');
    },
    fullscreen: () => {
      Alert.alert('fullscreen');
    },
  }}
/>
```

## errorOverride

`Android` `iOS`

기본으로 제공되는 에러 화면을 원하는 코드로 변경하여 실행할 수 있습니다. 에러 화면을 재정의하면 마지막 재생 위치에서 정지(pause) 상태를 유지한 채 플레이어 오버레이를 통해 에러 화면을 구현할 수 있습니다.

```
<VpePlayer
  errorOverride={(res) => {
    return (
      <>
        <View>
          <Text style={{ color: '#ffffff', fontSize: 16, paddingVertical: 8 }}>
            {res.error.title}
          </Text>
        </View>
        <View>
          <Text style={{ color: '#ffffff', fontSize: 12, opacity: 0.8 }}>
            ({res.error.desc})
          </Text>
        </View>
        <View>
          <Text style={{ color: '#ffffff', fontSize: 12, opacity: 0.8, paddingTop: 10 }}>
            고객센터 문의 : 1588-0001
          </Text>
        </View>
      </>
    );
  }}
/>
```

## customButton

`Android` `iOS`

`customButton` 속성으로 플레이어에 커스텀 버튼을 추가하여 새로운 기능을 제공할 수 있습니다. 커스텀 버튼은 위치와 관계없이 최대 4개까지 추가할 수 있습니다.

`position` 및 `flow` 속성으로 버튼 위치를 지정합니다: `left-top`, `right-top`, `left-bottom`, `right-bottom`

```
<VpePlayer
  customButton={[
    {
      position: 'right-bottom',
      flow: 'left',
      button: () => {
        return (
          <TouchableOpacity onPress={() => { Alert.alert('test'); }}>
            <ChatCircleIcon size={22} color={'#ffffff'} weight={'fill'} />
          </TouchableOpacity>
        );
      },
    },
    {
      position: 'right-top',
      flow: 'left',
      button: () => {
        return (
          <TouchableOpacity onPress={() => { Alert.alert('test'); }}>
            <InfoIcon size={22} color={'#ffffff'} weight={'fill'} />
          </TouchableOpacity>
        );
      },
    },
  ]}
/>
```

## LLM 기반 코드 생성

`Android` `iOS`

VPE React Native SDK 설정을 빠르게 시작하기 위한 가이드입니다. `rn-llms.txt`를 프롬프트로 제공하면 AI가 React Native (Expo/Bare RN) 기반 예제 코드를 생성합니다.

### 개념

- rn-llms.txt는 VPE React Native SDK의 핵심 구조(VpePlayer / PlayerContext / layout 시스템 / IconOverrides / 제스처 / 옵션·이벤트)와 PR1·PR2 breaking changes를 한 문서에 정리한 요약 가이드입니다.
- 이를 LLM에 먼저 읽히면 코드 생성 시 필수 props·옵션과 권장 패턴을 누락하지 않도록 도와줍니다.

### LLM 선택

사용 중인 LLM(예: ChatGPT, Claude, Copilot, Cursor 등)에 아래 프롬프트를 그대로 붙여넣습니다.

### 프롬프트 입력

```
https://developer.vpe.naverncp.com/rn-llms.txt 읽고 React Native 예제 코드 생성해줘
```

### 예시 프롬프트

구체적인 시나리오를 함께 명시하면 더 정확한 코드를 얻을 수 있습니다.

```
https://developer.vpe.naverncp.com/rn-llms.txt 참고해서
Expo 53 + React Navigation 환경에서 다음을 만족하는 VpePlayer 화면을 만들어줘.

- accessKey 와 platform='pub' 사용
- HLS playlist 1개, autostart + muted
- 커스텀 layout으로 BackBtn(events.backPress로 navigation.goBack 호출),
  ShareBtn, SettingBtn 을 top 우측에 배치
- options.icon 으로 play/pause 아이콘을 phosphor-react-native 로 교체
- 전체화면은 modalFullscreen: false 로 커스텀 풀스크린 처리
```

### 가이드

- 응답 코드에서 `accessKey`, `playlist` URL은 프로젝트 환경에 맞게 교체합니다.
- Expo Go 환경에서는 `devTestAppId`를 함께 전달해야 라이선스 체크를 우회할 수 있습니다.
- 구버전(0.x)에서 마이그레이션 시 LLM에 "PR1/PR2 breaking changes 적용해서"라고 명시해 주십시오. (`backButton` → `events.backPress`, `props.icon` → `options.icon`, `PipBtn` 폐지)
- 레이아웃을 커스터마이징할 때는 "섹션 단위 replace"이므로 필요한 섹션만 정의해도 나머지는 디폴트가 사용됩니다.
- PIP, 화면 캡처 방지, 백그라운드 재생 등은 `app.json` 설정도 함께 요청해 주십시오.
- 결과가 길 경우, “필요한 부분만 요약해줘”라고 추가로 요청할 수 있습니다.