Web Player Controller

개요

Web Player Controller(구 VG Controller)는 고객사의 웹사이트에 iframe으로 삽입된 Kollus 플레이어와 통신하여, 재생 상태를 제어하거나 실시간 이벤트를 수신할 수 있게 해주는 JavaScript 라이브러리입니다.

주요 특징

통합 제어: 플레이어 종류와 관계없이 단일 규격으로 제어 가능합니다.
독립적 구동: 별도의 외부 라이브러리 의존성 없이 독립적으로 동작합니다.
이벤트 기반 구조: 메서드 호출 및 실시간 이벤트 리스너 구조를 지원합니다.

용어 정의

이 문서에서 사용하는 주요 기술 용어와 플레이어 표기에 대한 정의입니다.

용어	설명
VideoGateway	시청자 요청에 따라 재생 데이터 및 인증 정보를 전달하는 서버
플레이어 ID	시청자 디바이스 고유 식별자
하드웨어 ID	시청자 하드웨어 시리얼 넘버 (Windows 환경 등 식별 가능한 값이 존재하는 경우 제공)
HLS Fragment	HLS(HTTP Live Streaming) 프로토콜 기반 재생 시 전체 영상을 분할한 최소 단위의 미디어 세그먼트 파일
v3	Html5 Player for PC (Hybrid): Microsoft Edge 또는 Chrome 45 이상에서 암호화 콘텐츠 재생 시 적용되는 하이브리드 HTML5 플레이어
v4	Html5 Player for All: 비암호화 콘텐츠 전용 비설치형 HTML5 플레이어
v5	Web Player: 설치형과 비설치형의 장점을 결합한 차세대 통합 웹 플레이어

ℹ️플레이어 안내

Kollus 플레이어에 대한 상세 설명은 아래 문서를 참고하세요.

Kollus 플레이어 종류

라이브러리 설치 및 초기화

클라이언트 스크립트를 로드한 후, 제어 대상(iframe)을 지정하여 인스턴스를 생성합니다.

기본 구현 예제

<script src="https://file.kollus.com/vgcontroller/vg-controller-client.latest.min.js"></script>
<script>
window.onload = function () {
  try {
    var controller = new VgControllerClient({
      target_window: document.getElementById('child').contentWindow,
    });
    // Register event listeners and call methods
  } catch (e) {
    console.error(e);
  }
};
</script>
<body>
  <iframe id="child" src="http://v.kr.kollus.com/{MEDIA_CONTENT_KEY}..."></iframe>
</body>

주의 사항

대상 지정: target_window 속성에는 반드시 iframe 요소의 contentWindow 객체를 전달해야 합니다.
브라우저 호환성: 이 라이브러리는 window.postMessage API를 사용하여 통신합니다. 해당 API를 지원하지 않는 브라우저에서는 작동이 제한됩니다.
다중 플레이어 제어: 페이지 내 여러 개의 플레이어(iframe)가 존재할 경우, 각 iframe ID별로 개별 인스턴스를 생성해야 합니다.

예외 코드

초기화 및 통신 과정에서 발생할 수 있는 에러 코드입니다.

코드	메시지	설명
`-1`	*	`postMessage` 통신 중 발생한 예외
`-99`	player type is not defined	플레이어 유형 정보 누락
`-99`	player type must be one of v2, v3, v4 and flash	지원하지 않는 플레이어
`-99`	this browser does not support postMessage	브라우저의 `postMessage` API 미지원
`-99`	listener is not callable	등록하려는 이벤트 리스너가 유효한 함수가 아님

CDN 경로

Web Player Controller는 CDN을 통해 제공됩니다.

특정 버전 고정

<script src="https://file.kollus.com/vgcontroller/vg-controller-client.1.1.4.min.js"></script>

보안 강화 (SRI 적용)

라이브러리 변조 방지를 위한 SRI(Subresource Integrity) 속성 사용을 권장합니다.

<script src="https://file.kollus.com/vgcontroller/vg-controller-client.1.2.3.min.js"
  integrity="sha256-esUCCL4RPYMS8AR+Sl3lNrFa5M+zgpt4Gb77qtz66OY=" 
  crossorigin="anonymous">
</script>

ℹ️참고

버전별 Integrity 속성(Integrity Code)은 CDN 목록을 참고하세요.

이벤트 리스닝

controller.on() 메서드를 활용하여 플레이어의 상태 변화 및 재생 이벤트를 실시간으로 수신합니다.

리스너 등록 방식

단일 리스너

controller.on('event_name', function(param) {
  // Register event listener
});

다중 리스너

controller.on('event_name', function(param) {
  // First listener
});
controller.on('event_name', function(param) {
  // Second listener
});
// Execute all listeners when the event is fired

메서드 체이닝 (Method Chaining)

연속적인 이벤트 등록을 간결한 코드로 구현할 수 있습니다.

controller.on('event_name_1', function(param) {
  // First listener
}).on('event_name_2', function(param) {
  // Second listener
});

⚠️리스너 실행 순서

JavaScript 비동기 환경 특성상, 동일 이벤트에 등록된 여러 리스너 간의 실행 순서는 보장되지 않습니다.

권장 사항: 엄격한 실행 순서가 필요한 로직은 하나의 리스너 내부에서 순차적으로 작성하세요.

이벤트 목록

재생 상태 이벤트

이벤트	지원 플레이어	설명
`loaded`	v3, v4	플레이어 구성 요소의 로딩이 완료된 시점에 발생
`ready`	v3, v4	서버로부터 재생 데이터를 수신하여 재생 준비가 완료된 시점에 발생
`play`	v3, v4	최초 재생 시작 또는 일시정지 후 재생 재개 시 발생
`pause`	v3, v4	일시정지 시 발생
`done`	v3, v4	재생 시점이 전체 길이(`duration`) 끝에 도달했을 때 발생
`waiting`	v4	네트워크 환경 영향으로 추가 버퍼링이 필요한 경우, 정상화 전까지 1초 주기로 발생

진행률(Progress) 이벤트

이벤트	지원 플레이어	설명
`progress`	v3, v4	재생 중 약 1초 간격으로 발생하며 현재 재생 위치 정보 전달

progress 파라미터 상세

파라미터	타입	설명
`percent`	integer	현재 재생 진행률 (0~100)
`position`	number	현재 재생 위치 (s)
`duration`	number	콘텐츠 전체 길이 (s)

controller.on('progress', function(percent, position, duration) {
  console.log(percent + '%', position + 'sec');
});

⚠️주의

HTML5 브라우저 성능 및 네트워크 환경에 따라 progress 이벤트는 정확히 1초 간격이 아닌 약 0.1~0.5초의 오차가 발생할 수 있습니다.

탐색(Seek) 이벤트

이벤트	지원 플레이어	설명
`seeking`	v4	시청자가 재생 시점 이동을 시작한 시점에 발생
`seeked`	v4	재생 시점 이동 작업이 완료된 시점에 발생
`seek_start`	v4, v5	재생 시점 이동이 감지된 최초 시점에 발생

음향 이벤트

이벤트	지원 플레이어	설명
`muted`	v3, v4	음소거 상태(On/Off) 변경 시 발생
`volumechange`	v3, v4	음량 수치 변경 시 발생

muted 파라미터 상세

파라미터	타입	설명
`is_muted`	boolean	`true`: 음소거 적용 `false`: 음소거 해제

volumechange 파라미터 상세

파라미터	타입	설명
`volume`	integer	변경된 음량 수치 (0~100)

재생속도(배속) 이벤트

이벤트	지원 플레이어	설명
`speedchange`	v3, v4	재생속도 변경 시 발생
`playbackrateschange`	v3, v4	사용 가능한 배속값 그룹 변경 시 발생

speedchange 파라미터 상세

파라미터	타입	설명
`speed`	string	변경된 배속 (0.5~4)

화면 이벤트

이벤트	지원 플레이어	설명
`screenchange`	v3, v4	전체 화면 모드와 일반 모드 간 전환 시 발생
`device_orientation_changed`	v4	모바일 화면 방향(가로/세로) 변경 시 발생
`user_active_changed`	v4	사용자 인터랙션에 의한 컨트롤바 활성화/비활성화 상태 변경 시 발생

screenchange 파라미터 상세

파라미터	타입	설명
`screen`	string	`windowed`: 일반 모드 `fullscreen`: 전체 화면 모드

device_orientation_changed 파라미터 상세

파라미터	타입	설명
`orientation`	string	`Portrait`: 세로 방향 `Landscape`: 가로 방향

자막 이벤트

이벤트	지원 플레이어	설명
`subtitle_load_done`	v3, v4	자막 파일 로드가 완료된 시점에 발생
`subtitlevisibilitychange`	v3, v4	자막 노출 상태(On/Off) 변경 시 발생

스트리밍 이벤트

이벤트	지원 플레이어	설명
`hls_manifest_loaded`	v4	HLS Manifest 파일 로드 완료 시 발생
`dash_manifest_loaded`	v4	DASH Manifest 파일 로드 완료 시 발생
`bitrate_data_loaded`	v4	비트레이트 데이터 로드 완료 시 발생 (오름차순 정렬)
`hlsfragchange`	v4	HLS Fragment 변경 시 발생

bitrate_data 형식 예시

controller.on('bitrate_data_loaded', function(bitrate_data) {
  // bitrate_data format: [{ width: <int>, height: <int>, bitrate: <int> }]
});

기타 이벤트

이벤트	지원 플레이어	설명
`error`	v3, v4	재생 중 시스템 오류 발생 시 호출
`html5_video_supported`	v3, v4	브라우저의 HTML5 Video 기능 지원 여부 확인 시 호출
`jumpstepchange`	v3, v4	구간 이동(빨리감기/되감기) 시간 단위 변경 시 발생
`bookmark_change`	v3	북마크 추가, 업데이트, 삭제 시 발생
`next_episode_auto_change`	v3, v4, v5	다음 회차 자동 재생 설정 변경 시 발생
`next_episode_requested`	v3, v4, v5	다음 회차 콜백이 요청된 시점에 발생
`picture_in_picture_entered`	v3, v4, v5	PIP(Picture-in-Picture) 모드 진입 시 발생
`picture_in_picture_leaved`	v3, v4, v5	PIP 모드 종료 시 발생

메서드 사용법

VG Controller 인스턴스를 통해 생성된 객체로 플레이어의 동작을 직접 제어할 수 있습니다.

기본 호출 방식

별도의 인자가 필요 없는 제어 명령은 메서드를 직접 호출합니다.

controller.play();

파라미터 전달 방식

설정값이 필요한 제어 명령은 메서드의 인자로 파라미터를 전달합니다.

controller.set_volume(90);

메서드 목록

이벤트 리스너 메서드

메서드	지원 플레이어	설명
`on(event_name, callback)`	v3, v4	이벤트 리스너 등록 및 `VgControllerClient` 인스턴스 반환
`off(event_name)`	v3, v4	특정 이벤트에 등록된 모든 리스너 일괄 제거

재생 메서드

메서드	지원 플레이어	설명
`play([start_at])`	v3, v4	재생 시작 (`start_at`(s) 지정 시 해당 시점부터 즉시 재생)
`pause()`	v3, v4	현재 재생 중인 콘텐츠 일시정지
`toggle_pip()`	v3, v4	PIP(Picture-in-Picture) 모드 활성화 상태 전환
`get_progress()`	v3, v4	현재 재생 정보(`percent, position, duration`) 반환

play 메서드 호출 예시

재생을 시작합니다.
```
controller.play();
```
10초 시점부터 재생합니다.
```
controller.play(10);
```

탐색(Seek) 메서드

메서드	지원 플레이어	설명
`ff()`	v3, v4	설정된 `jumpstep`만큼 앞으로 이동 (빨리감기, 기본값: 10초)
`rw()`	v3, v4	설정된 `jumpstep`만큼 뒤로 이동 (되감기, 기본값: 10초)
`set_current_time(time)`	v3, v4	재생 상태를 유지하며 지정 시점(`time`)으로 이동
`get_current_time()`	v3, v4	현재 재생 위치 반환
`set_jumpstep(jumpstep)`	v3, v4	`ff()` 또는 `rw()` 호출 시 이동할 시간 간격(s) 설정
`get_jumpstep()`	v3, v4	현재 설정된 `jumpstep` 값 반환
`set_keyframe_seek_default(is_default)`	V2	키프레임 단위 이동을 기본값으로 설정

ℹ️참고

play([start_at])와 set_current_time(time)의 차이

play(10): 10초 위치로 이동한 후 즉시 재생 시작
set_current_time(10): 10초 위치로 이동하지만, 기존 재생/일시정지 상태 유지

음향 메서드

메서드	지원 플레이어	설명
`set_volume(volume)`	v3, v4	음량 설정 (0~100)
`get_volume()`	v3, v4	현재 설정된 음량 수치 반환
`mute()`	v3, v4	음소거 상태 전환 (On/Off)

화면 메서드

메서드	지원 플레이어	설명
`set_screen()`	v3, v4	전체 화면 모드와 일반 모드 간 전환 수행
`get_screen()`	v3, v4	현재 화면 모드 반환 `windowed`: 일반 모드 `fullscreen`: 전체 화면 모드
`set_fullscreen_element(element)`	v3, v4	전체 화면 전환 시 대상으로 지정할 DOM 요소 설정
`enable_fullscreen_button()`	v3, v4	플레이어 UI 내의 전체 화면 전환 버튼 활성화
`set_video_visibility(visibility)`	v3, v4	비디오 화면 노출 여부 설정 (오디오 재생은 유지)
`get_video_visibility()`	v3, v4	비디오 화면의 현재 노출 상태 반환
`set_ratio(type)`	v3, v4	화면 확대 및 비율 방식 설정 `contain`: 가로/세로 비율을 유지하며 화면에 맞춤 `fill`: 비율과 관계없이 화면 전체를 채움 `enlargement`: 세로 길이를 기준으로 맞춤 (좌우 스크롤 발생 가능)

⚠️주의

set_screen() 메서드는 Flash Player 및 FireFox 브라우저에서 지원되지 않습니다.

컨트롤바 메서드

메서드	지원 플레이어	설명
`set_control_visibility(visibility)`	v3, v4	내장 컨트롤바 노출 여부 설정
`get_control_visibility()`	v3, v4	내장 컨트롤바 현재 노출 상태 반환
`set_controls_inactive_time(time)`	v3, v4	컨트롤바 자동 숨김 대기 시간 설정 (`0`: 상시 노출)
`get_controls_inactive_time()`	v3, v4	설정된 컨트롤바 자동 숨김 시간 반환
`set_controls_activity(activity)`	v3, v4	컨트롤바 활성화 여부 설정
`get_controls_activity()`	v3, v4	컨트롤바 활성화 상태 반환
`set_controlbar_progress_only(enable)`	v3, v4	프로그레스 바(Progress Bar)만 노출하고 기타 제어 버튼 숨김 처리
`get_controlbar_progress_only()`	v3, v4	프로그레스 바 단독 노출 여부 반환
`set_controlbar_hide_playing(enable)`	v4	재생 중 컨트롤바 자동 숨김 여부 설정
`get_controlbar_hide_playing()`	v4	재생 중 컨트롤바 자동 숨김 설정 여부 반환
`hide_controlbar_button(value)`	v3, v4, v5	버튼을 컨트롤바에서 숨김 (`ready` 이벤트 이후 호출 권장) `play`: 재생 `rewind`: 되감기 `forward`: 빨리감기 `repeat`: 구간 반복 `currenttime`: 현재 재생 시간 `durationtime`: 총 재생 시간 `quality`: 화질 `playbackrate`: 배속 `mute`: 음소거 `volume`: 볼륨 그래프 `subtitle`: 자막 `setting`: 설정 `fullscreen`: 전체 화면 모드 `chat`: 채팅 `pip`: PIP 모드 `bigplay`: 중앙 재생 버튼 (Kollus Web Player) `seekcontainer`: 모바일 좌우 되감기/빨리감기 (Kollus Web Player)

hide_controlbar_button 메서드 호출 예시

컨트롤바에서 전체 화면 모드 및 설정 버튼을 숨김 처리합니다.

controller.hide_controlbar_button(['fullscreen', 'setting']);

재생속도(배속) 메서드

메서드	지원 플레이어	설명
`set_speed(speed)`	v3, v4	재생속도를 0.5~4 범위 내에서 0.1초 단위로 설정
`get_speed()`	v3, v4	현재 적용 중인 재생속도를 문자열 형태로 반환
`set_playback_rates(rates)`	v3, v4	플레이어 UI에 노출될 배속값 그룹 설정
`get_playback_rates()`	v3, v4	현재 설정된 배속값 그룹을 문자열 형태로 반환

메서드 호출 예시

단일 배열: 배속 옵션을 한 줄로 나열하여 구성합니다.
```
controller.set_playback_rates([0.5, 1, 1.5, 2]);
```

이중 배열: [배속값 배열, 표시할 행(Row) 수]

controller.set_playback_rates([[0.5, 1, 1.5, 2, 3, 4], 2]);

ℹ️참고

iOS 환경에서 HLS 방식으로 시청할 경우, 운영체제 정책 및 기술 규격에 따라 최대 2.0배속까지만 지원됩니다.

구간 반복 메서드

메서드	지원 플레이어	설명
`set_repeat_start([position])`	v3, v4	구간 반복 시작 시점 설정 (인자 생략 시 현재 재생 위치를 기준으로 설정)
`set_repeat_end([position])`	v3, v4	구간 반복 종료 시점 설정 (인자 생략 시 현재 재생 위치를 기준으로 설정)
`unset_repeat()`	v3, v4	활성화된 구간 반복 설정을 해제하고 일반 재생 모드로 전환
`get_repeat()`	v3, v4	현재 구간 반복 상태 정보(`status, start, end`) 반환

set_repeat 메서드 호출 예시

10초 시점을 반복 시작 지점으로 설정합니다.
```
controller.set_repeat_start(10);
```
20초 시점을 반복 종료 시점으로 설정합니다.
```
controller.set_repeat_end(20);
```

북마크 메서드

메서드	지원 플레이어	설명
`refresh_bookmark()`	v3, v4	서버로부터 최신 북마크 목록을 동기화하여 업데이트 수행
`get_bookmark_count()`	v3, v4	모든 북마크, 공식 북마크, 내 북마크 개수(`all, index, user`) 반환
`set_bookmark_add_activation(activation)`	v3, v4, v5	플레이어 UI 내 북마크 추가 버튼 활성화 여부 설정
`set_bookmark_update_activation(activation)`	v3, v4, v5	플레이어 UI 내 북마크 편집 버튼 활성화 여부 설정

🚨기능 중단

Deprecated set_bookmark_add_visivility 및 set_bookmark_update_visivility 메서드는 더 이상 지원되지 않습니다. 위 표에 명시된 activation 계열 메서드를 사용하세요.

자막 메서드

메서드	지원 플레이어	설명
`set_subtitle(value)`	v3, v4	자막 데이터(VTT URL 또는 RawData) 직접 설정
`set_subtitle_visibility(visibility)`	v3, v4	메인 자막 노출 여부 설정
`set_subtitle_sub_visibility(visibility)`	v3, v4	서브 자막 노출 여부 설정
`set_subtitle_shadow_rect(is_rect)`	v3, v4	자막 배경 스타일 설정
`get_subtitle_shadow_rect()`	v3, v4	현재 설정된 자막 배경 스타일 값 반환
`set_subtitle_font_size(size)`	v3, v4	자막 텍스트 크기(px) 설정
`get_subtitle_font_size()`	v3, v4	현재 설정된 자막 텍스트 크기 반환
`set_subtitle_activity(activity)`	v3, v4	자막 노출 위치 설정
`get_subtitle_activity()`	v3, v4	자막 노출 위치 반환
`get_subtitles_list()`	v3, v4	전체 메인 자막 목록 반환
`get_subtitles_sub_list()`	v3, v4	전체 서브 자막 목록 반환
`set_current_subtitle(index)`	v3, v4	지정한 인덱스의 메인 자막으로 전환
`set_current_subtitle_sub(index)`	v3, v4	지정한 인덱스의 서브 자막으로 전환

비트레이트 메서드

메서드	지원 플레이어	설명
`set_bitrate(index)`	v4	지정한 인덱스의 비트레이트로 전환 (`0`: 자동)
`get_bitrate_data()`	v4	사용 가능한 비트레이트 목록 반환

ℹ️인덱스(Index) 지정 규칙

get_bitrate_data()를 통해 반환된 배열의 인덱스는 0부터 시작합니다.
set_bitrate() 메서드로 실제 변경을 요청할 때는 해당 배열 인덱스에 +1을 한 값을 인자로 전달해야 합니다.

플레이어 정보 메서드

메서드	지원 플레이어	설명
`get_player_id()`	v3, v4	플레이어 ID 반환 (`ready` 이벤트 이후 호출 가능)
`get_hardware_id()`	v3	하드웨어 ID 반환 (`ready` 이벤트 이후 호출 가능)
`get_player_type()`	v3, v4	현재 실행 중인 플레이어 종류 반환 `v3`: Html5 Player for PC (Hybrid) `v4`: Html5 Player for All
`get_video_info()`	v3, v4	콘텐츠 해상도 및 비트레이트 정보(`width, height, bitrate`) 반환 (`ready` 이벤트 이후 호출 가능)
`get_lms_data()`	v3, v4	학습 관리 시스템(LMS) 연동 데이터 반환
`get_hls_frag_data()`	v4	HLS Fragment 관련 데이터 반환
`dispose()`	v4	플레이어 인스턴스 제거

커스텀 스킨 메서드

메서드	지원 플레이어	설명
`get_custom_skin()`	v4	현재 플레이어에 적용 중인 커스텀 스킨 설정(JSON) 반환 (`ready` 이벤트 이후 호출 가능)
`set_custom_skin(json_data)`	v4	JSON 형식의 설정 데이터를 주입하여 커스텀 스킨 변경 (`ready` 이벤트 이후 호출 가능)

set_custom_skin 메서드 호출 예시

controller.set_custom_skin({
  controlbar: {
    enable: true,
    backgroundColor: 123123,
    backgroundAlpha: 0.2,
    progressButton: {
      enable: false
    }
  }
});

에러 메서드

메서드	지원 플레이어	설명
`get_error_detail()`	v3, v4	현재 발생한 에러의 상세 정보(`code, message, param`) 반환
`set_custom_error(code, message, param)`	v3, v4	기본 에러 화면 대신 개발자가 정의한 커스텀 에러 코드와 메시지를 플레이어 UI에 노출

채팅 메서드

메서드	지원 플레이어	설명
`set_chat_config(value)`	v3, v4	채팅 관련 설정 적용 (`ready` 이벤트 이후 호출 가능)
`notify_visibleheight_changed(height)`	v3, v4	Android WebView 환경에서 키보드 활성화에 따른 화면 높이 변화값 전달

set_chat_config 메서드 호출 예시

controller.set_chat_config({
  customer_page: [{
    title: 'Class Title',
    url: 'https://example.com'
    // or 
    // html: '<h2>Custom HTML</h2>'
  }]
});

ℹ️참고

보안 정책: 외부 페이지 주입 시 https 프로토콜이 적용된 URL만 허용됩니다.
스크립트 제약: html 속성으로 전달된 본문 내 script 태그는 보안상의 이유로 실행이 제한됩니다.

클로즈 이벤트 메서드

메서드	지원 플레이어	설명
`set_enable_close_event()`	v3, v4	브라우저 종료(`close`) 감지 및 콜백 기능 활성화
`set_close_callback_fn(fn)`	v3, v4	브라우저 종료 시 실행할 사용자 정의 콜백 함수 등록
`get_enable_close_event()`	v3, v4	브라우저 종료(`close`) 콜백 할성화 여부 반환
`set_close_button(enable, fn)`	v4	모바일용 닫기 버튼 생성 및 클릭 이벤트 설정 (`ready` 이벤트 이후 호출 가능)

기타 메서드

메서드	지원 플레이어	설명
`set_vr_overlay(options)`	v3, v4	iOS 환경 내 VR 콘텐츠 재생을 위한 권한 요청 오버레이 설정
`set_short_key(enable)`	V2	플레이어 단축키 활성화 여부 설정
`get_topmost()`	V2	플레이어 창의 최상위 노출 설정 여부 반환
`set_topmost(topmost)`	V2	플레이어 창의 최상위 노출 여부 설정
`set_lms_check()`	V2	브라우저 종료 시 LMS 데이터 전송 완료 여부 확인 설정

모바일 VR 콘텐츠 재생 시 유의 사항

모바일 브라우저의 보안 정책 및 iframe 환경의 기술적 제약으로 인해 VR(360°) 콘텐츠 재생 시 아래 사항을 확인해야 합니다.

Android: iframe 내에서 디바이스의 orientation(방향) 정보 동기화 이슈로 인해, VR 영상의 좌우 조작 방향이 실제 디바이스 움직임과 반대로 작동하는 현상이 발생할 수 있습니다.
iOS: iOS 13 버전부터 보안 강화를 위해 DeviceMotion(가속도/자이로) 데이터 접근 시 사용자 승인이 필수입니다. 하지만 브라우저 보안 정책상 iframe 내부에서는 권한 요청 팝업 호출이 제한되어 VR 조작 기능이 작동하지 않습니다.

해결 방법

VG Controller 1.1.10 이상 버전을 사용하세요.
iOS 환경에서는 set_vr_overlay() 메서드를 반드시 호출하세요.

var controller = new VgControllerClient({
  // Specify the top-level parent window containing the player iframe
  target_window: player.contentWindow
});
controller.set_vr_overlay({
  // Specify the target DOM element to display the permission request overlay
  target_element: document.getElementById('player'),
  // Set a custom message to guide users to grant motion and gyro sensor permissions
  permission_request_help_message: 'Please allow access to the accelerometer and gyroscope sensors to use VR features.'
});

🚨기술 이슈

iOS 13.4 이상 버전의 경우, Apple의 개인정보 보호 정책에 따라 DeviceMotion API의 rotationRate 값이 정상적으로 반환되지 않습니다.

개요​

주요 특징​

용어 정의​

라이브러리 설치 및 초기화​

기본 구현 예제​

주의 사항​

예외 코드​

CDN 경로​

최신 버전 자동 적용​

특정 버전 고정​

보안 강화 (SRI 적용)​

이벤트 리스닝​

리스너 등록 방식​

단일 리스너​

다중 리스너​

메서드 체이닝 (Method Chaining)​

이벤트 목록​

재생 상태 이벤트​

진행률(Progress) 이벤트​

progress 파라미터 상세​

탐색(Seek) 이벤트​

음향 이벤트​

muted 파라미터 상세​

volumechange 파라미터 상세​

재생속도(배속) 이벤트​

speedchange 파라미터 상세​

화면 이벤트​

screenchange 파라미터 상세​

device_orientation_changed 파라미터 상세​

자막 이벤트​

스트리밍 이벤트​

bitrate_data 형식 예시​

기타 이벤트​

메서드 사용법​

기본 호출 방식​

파라미터 전달 방식​

메서드 목록​

이벤트 리스너 메서드​

재생 메서드​

play 메서드 호출 예시​

탐색(Seek) 메서드​

음향 메서드​

화면 메서드​

컨트롤바 메서드​

hide_controlbar_button 메서드 호출 예시​

재생속도(배속) 메서드​

메서드 호출 예시​

구간 반복 메서드​

set_repeat 메서드 호출 예시​

북마크 메서드​

자막 메서드​

비트레이트 메서드​

플레이어 정보 메서드​

커스텀 스킨 메서드​

set_custom_skin 메서드 호출 예시​

에러 메서드​

채팅 메서드​

set_chat_config 메서드 호출 예시​

클로즈 이벤트 메서드​

기타 메서드​

모바일 VR 콘텐츠 재생 시 유의 사항​

해결 방법​

개요

주요 특징

용어 정의

라이브러리 설치 및 초기화

기본 구현 예제

주의 사항

예외 코드

CDN 경로

최신 버전 자동 적용

특정 버전 고정

보안 강화 (SRI 적용)

이벤트 리스닝

리스너 등록 방식

단일 리스너

다중 리스너

메서드 체이닝 (Method Chaining)

이벤트 목록

재생 상태 이벤트

진행률(Progress) 이벤트

progress 파라미터 상세

탐색(Seek) 이벤트

음향 이벤트

muted 파라미터 상세

volumechange 파라미터 상세

재생속도(배속) 이벤트

speedchange 파라미터 상세

화면 이벤트

screenchange 파라미터 상세

device_orientation_changed 파라미터 상세

자막 이벤트

스트리밍 이벤트

bitrate_data 형식 예시

기타 이벤트

메서드 사용법

기본 호출 방식

파라미터 전달 방식

메서드 목록

이벤트 리스너 메서드

재생 메서드

play 메서드 호출 예시

탐색(Seek) 메서드

음향 메서드

화면 메서드

컨트롤바 메서드

hide_controlbar_button 메서드 호출 예시

재생속도(배속) 메서드

메서드 호출 예시

구간 반복 메서드

set_repeat 메서드 호출 예시

북마크 메서드

자막 메서드

비트레이트 메서드

플레이어 정보 메서드

커스텀 스킨 메서드

set_custom_skin 메서드 호출 예시

에러 메서드

채팅 메서드

set_chat_config 메서드 호출 예시

클로즈 이벤트 메서드

기타 메서드

모바일 VR 콘텐츠 재생 시 유의 사항

해결 방법