Web Player Controller

개요

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

주요 특징

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

용어 정의

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

용어	설명
비디오 게이트웨이	시청자 요청에 따라 재생 데이터 및 인증 정보를 전달하는 서버
플레이어 ID	Kollus 플레이어 고유 ID
하드웨어 ID	Windows 환경 등 식별 가능한 값이 존재하는 경우 제공되는 하드웨어 고유 ID
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="https://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, v5
`ready`	서버로부터 재생 데이터를 수신하여 재생 준비가 완료된 시점에 발생	v3, v4, v5
`play`	최초 재생 시작 또는 일시정지 후 재생 재개 시 발생	v3, v4, v5
`pause`	일시정지 시 발생	v3, v4, v5
`done`	재생 시점이 전체 길이(`duration`) 끝에 도달했을 때 발생	v3, v4, v5
`waiting`	네트워크 환경 영향으로 추가 버퍼링이 필요한 경우, 정상화 전까지 1초 주기로 발생	v4, v5

진행률(Progress) 이벤트

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

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, v5
`seeked`	재생 시점 이동 작업이 완료된 시점에 발생	v4, v5
`seek_start`	재생 시점 이동이 감지된 최초 시점에 발생	v4, v5

음향 이벤트

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

muted 파라미터 상세

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

volumechange 파라미터 상세

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

재생속도(배속) 이벤트

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

speedchange 파라미터 상세

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

화면 이벤트

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

screenchange 파라미터 상세

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

device_orientation_changed 파라미터 상세

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

자막 이벤트

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

스트리밍 이벤트

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

bitrate_data 형식 예시

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

기타 이벤트

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

메서드 사용법

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

기본 호출 방식

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

controller.play();

파라미터 전달 방식

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

controller.set_volume(90);

메서드 목록

이벤트 리스너 메서드

메서드	설명	대상 플레이어
`on(event_name, callback)`	이벤트 리스너 등록 파라미터 `event_name` (`string`): 이벤트 이름 `callback` (`function`): 이벤트 발생 시 호출될 함수 반환값: `VgControllerClient` 인스턴스	v3, v4, v5
`off(event_name)`	특정 이벤트에 등록된 모든 리스너 일괄 제거 파라미터 `event_name` (`string`): 이벤트 이름	v3, v4, v5

재생 메서드

메서드	설명	대상 플레이어
`play([start_at])`	재생 시작 파라미터 (선택 사항) `start_at` (`integer`, sec): 해당 시점부터 즉시 재생 호출 예시 재생 시작: `controller.play();` 10초 시점부터 재생: `controller.play(10);`	v3, v4, v5
`pause()`	현재 재생 중인 콘텐츠 일시정지	v3, v4, v5
`toggle_pip()`	PIP(Picture-in-Picture) 모드 활성화 상태 전환	v3, v4, v5
`get_progress()`	현재 재생 정보(`percent, position, duration`) 반환	v3, v4, v5

탐색(Seek) 메서드

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

play([start_at])와 set_current_time(time) 비교

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

음향 메서드

메서드	설명	대상 플레이어
`set_volume(volume)`	음량 설정 파라미터 `volume` (`integer`, 0~100): 설정할 음량	v3, v4, v5
`get_volume()`	현재 설정된 음량 수치 반환	v3, v4, v5
`mute()`	음소거 상태 전환 (On/Off)	v3, v4, v5

화면 메서드

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

컨트롤바 메서드

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

hide_controlbar_button 메서드 호출 예시

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

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

재생속도(배속) 메서드

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

set_playback_rates 메서드 호출 예시

단일 배열: 배속 옵션을 한 줄로 나열하여 구성합니다.

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, v5
`set_repeat_end([position])`	구간 반복 종료 시점 설정 (인자 생략 시 현재 재생 위치를 기준으로 설정)	v3, v4, v5
`unset_repeat()`	활성화된 구간 반복 설정을 해제하고 일반 재생 모드로 전환	v3, v4, v5
`get_repeat()`	현재 구간 반복 상태 정보(`status, start, end`) 반환	v3, v4, v5

set_repeat 메서드 호출 예시

10초 시점을 반복 시작 지점으로 설정합니다.

controller.set_repeat_start(10);

20초 시점을 반복 종료 시점으로 설정합니다.

controller.set_repeat_end(20);

북마크 메서드

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

Deprecated

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

자막 메서드

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

챕터 메서드

메서드	설명	대상 플레이어
`set_chapter_data(data)`	챕터 데이터 설정	v5
`get_chapter_data()`	현재 설정된 챕터 데이터 반환	v5

set_chapter_data(data)의 data 파라미터는 URL String 또는 JSON 형식만 허용됩니다.

// URL String
controller.set_chapter_data('https://example.com/chapters.json');

// JSON
controller.set_chapter_data({
  "ko": [
    {
      "position": 0,
      "value": "first"
    },
    {
      "position": 30,
      "value": "second"
    }
  ],
  "default_language_code": "ko"
});

챕터 데이터가 변경되면 기타 이벤트 이벤트가 발생합니다.

비트레이트 메서드

메서드	설명	대상 플레이어
`set_bitrate(index)`	지정한 인덱스의 비트레이트로 전환. `set_bitrate()` 메서드로 실제 변경을 요청할 때는 해당 배열 인덱스에 +1을 한 값을 인자로 전달해야 합니다. (`0`: 자동)	v4, v5
`get_bitrate_data()`	사용 가능한 비트레이트 목록 반환. `get_bitrate_data()`를 통해 반환된 배열의 인덱스는 0부터 시작합니다.	v4, v5

플레이어 정보 메서드

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

커스텀 스킨 메서드

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

set_custom_skin 메서드 호출 예시

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

에러 메서드

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

채팅 메서드

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

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()`	브라우저 종료(`close`) 감지 및 콜백 기능 활성화	v3, v4, v5
`set_close_callback_fn(fn)`	브라우저 종료 시 실행할 커스텀 콜백 함수 등록	v3, v4, v5
`get_enable_close_event()`	브라우저 종료(`close`) 콜백 할성화 여부 반환	v3, v4, v5
`set_close_button(enable, fn)`	모바일용 닫기 버튼 생성 및 클릭 이벤트 설정 (`ready` 이벤트 이후 호출 가능)	v4, v5

기타 메서드

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

모바일 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 형식 예시​

기타 이벤트​

메서드 사용법​

기본 호출 방식​

파라미터 전달 방식​

메서드 목록​

이벤트 리스너 메서드​

재생 메서드​

탐색(Seek) 메서드​

음향 메서드​

화면 메서드​

컨트롤바 메서드​

hide_controlbar_button 메서드 호출 예시​

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

set_playback_rates 메서드 호출 예시​

구간 반복 메서드​

set_repeat 메서드 호출 예시​

북마크 메서드​

자막 메서드​

챕터 메서드​

비트레이트 메서드​

플레이어 정보 메서드​

커스텀 스킨 메서드​

set_custom_skin 메서드 호출 예시​

에러 메서드​

채팅 메서드​

set_chat_config 메서드 호출 예시​

클로즈 이벤트 메서드​

기타 메서드​

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

해결 방법​

개요