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 の仕様

Prev Next

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に移行されました。詳細な使用方法は、カスタムアイコンのドキュメントをご参照ください。

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 / レイアウトシステム / 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 設定についても併せてリクエストしてください。
  • 結果が長すぎる場合は、「必要な部分だけを要約して」と追加でリクエストできます。
事業者登録番号: 129-86-31394 通信販売業申告番号:第2009-京畿城南-0510号
代表取締役: キム・ユウォン アドレス: 13561 京畿道 城南市 盆唐区 仏亭路6 グリーンファクトリー, 17~26F お客様センターの代表電話: 1544-5876
© NAVER Cloud Corp. All Rights Reserved.