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.

Installation and initial setup

Install npm

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

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); },
  }}
/>

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 logic (for example: navigation.goBack()).

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

options.icon (custom icon)

Layout

Android iOS

You can configure control layouts, groups, and environment-specific settings declaratively within the ControlBar. See 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 with 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, and 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

Copy and 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.

Referring to https://developer.vpe.naverncp.com/rn-llms.txt and create a VpePlayer interface
for an Expo 53 + React Navigation environment that satisfies the following requirements:

- 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.
- Handle Full screen with a custom implementation by setting 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."