Web Player Controller

개요

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

주요 특징

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

용어 정의

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

용어	설명
비디오 게이트웨이	시청자 요청에 따라 재생 데이터 및 인증 정보를 전달하는 서버
플레이어 ID	Kollus 플레이어 고유 ID
하드웨어 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`	현재 재생 위치 (sec)
`duration`	`number`	콘텐츠 전체 길이 (sec)

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 모드 종료 시 발생

메서드 사용법

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`(sec) 지정 시 해당 시점부터 즉시 재생)
`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()` 호출 시 이동할 시간 간격(sec) 설정
`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배속까지만 지원됩니다.

구간 반복 메서드

메서드	대상 플레이어	설명
`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	북마크 추가 버튼 활성화 여부 설정
`set_bookmark_update_activation(activation)`	v3, v4, v5	북마크 편집 버튼 활성화 여부 설정

Deprecated

set_bookmark_add_visibility 및 set_bookmark_update_visibility 메서드는 더 이상 지원되지 않습니다. 위 표에 명시된 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	사용 가능한 비트레이트 목록 반환

인덱스 지정 규칙

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

플레이어 정보 메서드

메서드	대상 플레이어	설명
`get_player_id()`	v3, v4	Kollus 플레이어 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.'
});

Issue

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 콘텐츠 재생 시 유의 사항​

해결 방법​

개요