---
title: "VPE 2.0 React Native の仕様"
slug: "vpe-v2-react-native-spec"
updated: 2026-10-20T09:07:02Z
published: 2026-10-20T09:07:02Z
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 の仕様

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はアプリ IDベースのライセンスが設定されます。開発環境でアプリ IDを開発専用に設定して、タスクが行えるようにサポートするプロパティです。

```
<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 / レイアウトシステム / IconOverrides / ジェスチャ / オプション・イベント)と、PR1・PR2 breaking changesを1つのドキュメントにまとめた要約ガイドです。
- これをまず 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` 設定についても併せてリクエストしてください。
- 結果が長すぎる場合は、「必要な部分だけを要約して」と追加でリクエストできます。