플레이어 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 시스템을 제공합니다.

값 유형

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

사용 가능한 키

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

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 />,      // 함수형 렌더러
    },
  }}
/>