---
title: "VPE 2.0 React Native prerequisites"
slug: "vpe-v2-react-native-spec"
updated: 2026-10-08T06:49:01Z
published: 2026-10-08T06:49:01Z
canonical: "guide.ncloud-docs.com/vpe-v2-react-native-spec"
---

> ## 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 prerequisites

Available in Classic and VPC

This guide explains how to install the VPE React Native SDK and configure your project.

## Supported environments

You can use the VPE React Native SDK in both Expo and React Native. Built on React Native video library v6.x and requires the `react-native >= 0.68.2` environment.

              Note

              

Expo Go does not support testing the VPE React Native SDK because the SDK uses native bridges. Use a development build instead.

## Installation and initial setup

### npm Installation

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

### Install dependencies

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

### Configure iOS in advance

              Note

              

If you build your app with Expo, you can skip this step.

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

### Set up a development test key and Test AppId

Video Player Enhancement validates the license using the AppId and AccessKey combination. Because Expo Go cannot use a production AppId, the SDK provides development-only props.

```
<VpePlayer
  devTestAppId={'TEST DEV AppID'} // Compatible with Expo Go and used exclusively in development mode
  accessKey={'VPE ACCESS KEY'}    // Access key matching the AppId
/>
```

### app.json configuration

You must add options to support `plugins` items along with Picture-in-Picture and 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

Show the list of properties available for configuring the player.

### devTestAppId

`Android` `iOS`

VPE is configured with an app ID-based license. This property allows you to work in the development environment by setting a development-only app ID.

```
<VpePlayer
  devTestAppId={'TEST DEV AppID'} // Compatible with Expo Go and used exclusively in development mode
/>
```

### accessKey

`Android` `iOS`

Set the VPE license key.

```
<VpePlayer
  accessKey={'VPE ACCESS KEY'} // Access key matching the AppId
/>
```

### platform

`Android` `iOS`

The VPE React Native SDK supports both public (`pub`) and government (`gov`) cloud environments. The default is public (`pub`).

```
<VpePlayer
  platform={'pub'} // pub: Public, gov: Government
/>
```

## Events

`Android` `iOS`

The VPE React Native SDK provides features to bind player events.

```
<VpePlayer
  events={{
    ready: () => {
      console.log('player ready');
    },
    fullScreen: (data) => {
      setIsFullScreen(data.isFullScreen);
    },
    timeupdate: (data) => {
      console.log('Total duration of the video (duration): ', data.duration);
      console.log('Current playback position (currentTime): ', data.currentTime);
      console.log('Current playback percentage (percent): ', data.percent);
      console.log('Accumulated playback time (viewingTime): ', data.viewingTime);
      console.log('Playback source type (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); },
  }}
/>
```

| Event | Description | Return value |
| --- | --- | --- |
| ready | Player loaded | - |
| fullScreen | Run Full screen | `data.isFullScreen` (true/false) |
| timeupdate | Playback | duration, currentTime, percent, viewingTime, sourceType |
| nextTrack | Move to next video | Next video source |
| prevTrack | Move to previous video | Previous video source |
| volumechange | Change player volume | Mute status |
| play | Start playback | - |
| pause | Stop playback | - |
| ended | Current video playback completed | - |
| controlbarActive | Enable control UI | - |
| controlbarDeactive | Disable control UI | - |
| backPress | Call when you click the BackBtn. You are responsible for handling the navigation logic | - |
| seeking/seeked | Navigation starts/completes | currentTime |
| error | An error occurs in the player | error_code, error_message |

## Options

`Android` `iOS`

Sets VPE player options. A separate page describes the player options in detail.

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

### events.backPress (back)

`Android` `iOS`

Breaking change: The existing `props.backButton` has been deprecated. Instead, place the `BackBtn` control within the layout and pass callbacks to `events.backPress`. You are responsible for handling navigation (e.g., `navigation.goBack()`).

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

### options.icon (custom icon)

              Note

              

**Breaking change**: The existing props.icon has moved to options.icon. See [Custom icon](https://developer.vpe.naverncp.com/docs/rn/custom-icon) documentation for detailed usage.

## Layout

`Android` `iOS`

You can configure control layouts, groups, and environment-specific settings declaratively within the ControlBar. See [Layout system](https://developer.vpe.naverncp.com/docs/rn/layout-system) documentation for further details.

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

## Override

`Android` `iOS`

You can directly override the basic features of the VPE player to implement your desired functionalities.

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

## errorOverride

`Android` `iOS`

You can replace the default error interface and Run your own implementation. When you override the error interface, you can implement a custom error interface as a player overlay while keeping the player paused at the last playback position.

```
<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 }}>
            Customer center: 1588-0001
          </Text>
        </View>
      </>
    );
  }}
/>
```

## customButton

`Android` `iOS`

New features can be provided by adding a custom button in the player with the `customButton` property. You can add up to 4 custom buttons regardless of the position.

The `position` and `flow` attributes determine the button position: `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-based code generation

`Android` `iOS`

This guide helps you quickly get started with VPE React Native SDK configuration. Provide `rn-llms.txt` as a prompt so the AI can generate React Native (Expo/Bare RN)-based sample code.

### Concepts

- rn-llms.txt is a summary guide that organizes the core structure of the VPE React Native SDK, including VpePlayer, PlayerContext, the layout system, IconOverrides, gestures, option events, along with PR1 and PR2 breaking changes.
- Providing this file to the LLM first helps you prevent the omission of essential props, options, and recommended patterns when the model generates code.

### Select an LLM

Paste the prompt below into the LLM you are using (e.g., ChatGPT, Claude, Copilot, Cursor, etc.):

### Enter the prompt

```
Read https://developer.vpe.naverncp.com/rn-llms.txt and generate React Native sample code.
```

### Example prompt

You can get a more accurate code by including a specific scenario.

```
See https://developer.vpe.naverncp.com/rn-llms.txt and create a VpePlayer interface.
In an Expo 53 + React Navigation environment, create a VpePlayer page that satisfies the following:

- Use accessKey and platform='pub'.
- Configure a single HLS playlist with autostart enabled and muted.
- Use a custom layout that places a BackBtn (calling navigation.goBack via events.backPress),
  ShareBtn, and SettingBtn in the top-right corner.
- Replace the play/pause icons with phosphor-react-native icons using options.icon.
- Full screen is handled as a custom full screen with modalFullscreen: false.
```

### Guide

- You must replace the `accessKey` and `playlist` URL within the response code to match your project environment.
- In Expo Go, pass `devTestAppId` together to bypass the license check.
- When migrating from a legacy version (0.x), tell the LLM to "apply PR1/PR2 breaking changes." (`backButton` → `events.backPress`, `props.icon` → `options.icon`, `PipBtn` deprecated)
- When you customize the layout, define only the sections you want to replace. The player uses the default layout for all other sections.
- Also request the `app.json` configuration for features such as PIP, screenshot prevention, and background playback.
- If the response is too long, you can also ask, "Summarize only the relevant sections."