---
title: "플레이어 UX"
slug: "vpe-rn-player-ux"
updated: 2026-09-17T09:08:03Z
published: 2026-09-17T09:08:03Z
canonical: "guide.ncloud-docs.com/vpe-rn-player-ux"
stale: true
---

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

# 플레이어 UX

Classic/VPC 환경에서 이용 가능합니다.

플레이어 UX를 구성하고 설정하는 옵션을 안내합니다.

## touchGestures (터치 제스처)

`touchGestures` 속성으로 모바일 UI에서 터치 제스처 기능을 활성화할 수 있습니다.

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDN도메인/example_video_01.mp4' },
    ],
    touchGestures: true, // 터치 제스처 사용(기본값)(false: 터치 제스처 사용 안 함)
  }}
/>
```

## watermarkText (텍스트 워터마크)

`watermarkText` 속성으로 시청자를 추적할 수 있는 워터마크를 원하는 텍스트(유저 아이디 + 사이트명 등)로 설정할 수 있습니다.

참조

이 기능을 사용하려면 콘솔에서 해당 플레이어의 워터마크 설정이 활성화되어 있어야 합니다. 워터마크 텍스트는 스크립트를 통해서만 추가할 수 있습니다.

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDN도메인/example_video_01.mp4' },
    ],
    visibleWatermark: true,
    watermarkText: 'UserId@SiteDomain',
  }}
/>
```

## watermarkConfig (텍스트 워터마크 상세 설정)

텍스트 워터마크 사용 시 워터마크 랜덤 위치 활성화 여부에 따라 상세 옵션을 설정할 수 있습니다. 워터마크 상세 옵션은 네이버 클라우드 플랫폼 콘솔에서도 설정할 수 있습니다.

**랜덤 위치 활성화**

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDN도메인/example_video_01.mp4' },
    ],
    visibleWatermark: true,
    watermarkText: 'UserId@SiteDomain',
    watermarkConfig: {
      randPosition: true,          // 워터마크 랜덤 위치 활성화(기본값)
      randPositionInterVal: 5000,  // 랜덤 변경 간격 (기본값: 3000ms)
    },
  }}
/>
```

**랜덤 위치 비활성화**

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDN도메인/example_video_01.mp4' },
    ],
    visibleWatermark: true,
    watermarkText: 'UserId@SiteDomain',
    watermarkConfig: {
      randPosition: false, // 워터마크 위치 고정
      x: 10,               // 가로 위치 (%)
      y: 2,                // 세로 위치 (%)
      opacity: 0.4,        // 투명도 (0.1 ~ 1)
    },
  }}
/>
```

## 전체화면 모드

전체화면을 모달(Modal) 또는 커스텀 전체화면 중 선택하여 개발할 수 있습니다. 모달 방식은 커스텀이 불가하나 기본적인 동작이 실행됩니다. 커스텀 전체화면은 안전 영역 및 동작 등을 직접 제어할 수 있습니다.

**모달형 전체화면**

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDN도메인/example_video_01.mp4' },
    ],
    modalFullscreen: true, // true: 모달 전체화면, false: 커스텀 전체화면
  }}
/>
```

**커스텀 전체화면**

```
import { View, StatusBar, ScrollView, Text } from 'react-native';
import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
import { VpePlayer } from 'vpe-react-native';
import React, { useRef, useState } from 'react';
import { useNavigation } from '@react-navigation/native';

export default function App() {
  const navigation = useNavigation();
  const [isFullScreen, setIsFullScreen] = useState(false);
  const playerRef = useRef(null);

  return (
    <SafeAreaProvider>
      <SafeAreaView edges={isFullScreen ? ['none'] : ['top', 'left', 'right']} />
      <StatusBar barStyle={'dark-content'} hidden={isFullScreen} />

      <VpePlayer
        ref={playerRef}
        devTestAppId={'com.vpereactnative.example'}
        accessKey={'YOUR_ACCESS_KEY'}
        platform={'pub'}
        events={{
          fullScreen: (data) => {
            setIsFullScreen(data.isFullScreen);
          },
        }}
        options={{
          playlist: [
            { file: 'https://CDN도메인/example_video_01.mp4' },
          ],
          aspectRatio: '16/9',
          objectFit: 'contain',
          modalFullscreen: false, // 커스텀 전체화면
        }}
      />

      {!isFullScreen && (
        <ScrollView style={{ backgroundColor: '#ffffff' }}>
          <View style={{ padding: 10 }}>
            <Text>커스텀 전체화면 구현 데모</Text>
          </View>
        </ScrollView>
      )}
    </SafeAreaProvider>
  );
}
```

## 커스텀 아이콘

지원 플랫폼: `Android` `iOS`

VPE React Native SDK는 Control Bar의 모든 기본 아이콘을 사용자 정의 아이콘(JSX, 원격 이미지 URL, 로컬 require 이미지, 함수형 렌더러)으로 교체할 수 있는 IconOverrides 시스템을 제공합니다.

참고

기존 `props.icon`은 폐지되었으며, `options.icon`으로 전달합니다.

### 값 유형

- ReactNode: JSX 직접 전달
- string: 원격 이미지 URL → 내부적으로 `&lt;Image source={{uri}} /&gt;` 렌더링
- number: `require('./icon.png')` 결과 → 로컬 이미지
- () => ReactNode: 동적 렌더링용 함수형

### 사용 가능한 키

아래 키들은 Control Bar의 기본 컨트롤 컴포넌트들이 참조하는 아이콘 이름입니다.

| 키 | 설명 |
| --- | --- |
| bigPlay | 중앙 큰 재생 버튼 |
| play | 재생 |
| pause | 일시정지 |
| replay | 재생 종료 후 다시보기 |
| prev | 이전 트랙 |
| next | 다음 트랙 |
| subtitle | 자막 ON |
| subtitleOff | 자막 OFF |
| fullscreen | 전체화면 진입 |
| fullscreenExit | 전체화면 종료 |
| volumeFull | 음량 최대 |
| volumeMid | 음량 중간 |
| volumeMute | 음소거 |
| setting | 설정 |
| back | 뒤로가기 |
| share | 공유 |
| skipForward | 10초 앞으로 |
| skipBack | 10초 뒤로 |

### JSX로 교체

```
import { VpePlayer } from 'vpe-react-native';
import { PlayIcon, PauseIcon } from 'phosphor-react-native';

export default function MyPlayer() {
  return (
    <VpePlayer
      accessKey={'YOUR_ACCESS_KEY'}
      options={{
        playlist: [{ file: 'https://CDN도메인/master.m3u8' }],
        icon: {
          play: <PlayIcon size={28} color="#ffffff" weight="fill" />,
          pause: <PauseIcon size={28} color="#ffffff" weight="fill" />,
        },
      }}
    />
  );
}
```

### 이미지로 교체

```
<VpePlayer
  accessKey={'YOUR_ACCESS_KEY'}
  options={{
    playlist: [{ file: 'https://CDN도메인/master.m3u8' }],
    icon: {
      play: 'https://example.com/icons/play.png', // 원격 이미지 URL (string)
      pause: require('./assets/pause.png'),        // 로컬 이미지 (require → number)
      fullscreen: () => <MyFullscreenIcon />,      // 함수형 렌더러
    },
  }}
/>
```