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 환경이 필요합니다.

설치 및 초기 설정

npm 설치

npm install vpe-react-native

의존성 설치

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

iOS 사전 설정

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

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 (커스텀 아이콘)

Layout

Android iOS

ControlBar의 컨트롤 배치, 그룹, 환경별 구성을 선언적으로 정의합니다. 자세한 내용은 레이아웃 시스템 문서를 참고해 주십시오.

<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 설정도 함께 요청해 주십시오.
• 결과가 길 경우, “필요한 부분만 요약해줘”라고 추가로 요청할 수 있습니다.