V/G Controller

Latest version 1.3.0

개요

Kollus VG Controller는 Videogateway로 제공되는 미디어의 일부 컨트롤을 고객사 웹사이트 내에서 구현 할 수 있도록 지원 하는 Javascript library입니다. Kollus VG Controller는 다음과 같은 특징을 가지고 있습니다.

Videogateway에서 자동으로 실행되는 플레이어의 타입에 관계없이 동일한 코드로 제어 가능
간단한 설치 + 쉬운 사용방법
플레이어의 감지 실행을 고민할 필요가 없음
서드파티 자바스크립트 라이브러리가 필요치 않음

메소드와 이벤트 목록 이름 옆에 표기되는 V3, V4 Player(1) 등은 Player를 의미합니다.

시작하기

VgControllerClient

(고객사 html page에 삽입)

아래 예시 코드를 영상이 보여질 html page에 적용하시면 됩니다.

...
<script src="/path/to/vg-controller-client.1.1.16.min.js"></script>
<script>
	window.onload = function () {
		try {
			var controller = new VgControllerClient({
				target_window: document.getElementById('child').contentWindow,
			});
			// 여기서부터 이벤트 리스너를 등록하거나, 웹페이지 Element에 메소드를 bind하면 됩니다.
		} catch (e) {
			// Videogateweay Controller Library는 window.postMessage API를 이용하기 때문에
			// 해당 기능을 지원하지 않는 웹브라우져에서는 동작하지 않습니다.
			// 이 부분에 적절한 fail-over 코드를 추가하여 주십시요.
			console.error(e);
		}
	};
</script>
<body>
	<iframe id="child" src="http://v.kr..."></iframe>
</body>
...

VgControllerClient 생성시 파라미터로 전달하는 target_window의 경우 홈페이지에 첨부한 Kollus Videogateway iframe의 HTMLElement에 contentWindow 속성을 입력해야 합니다
본 스크립트는 window.postMessage API 를 이용하여 Player와 통신하므로, 해당 기능을 지원하지 않는 웹브라우져에 서는 동작하지 않습니다.
웹페이지 내에 하나 이상의 iframe을 embed한 경우 제어할 iframe마다 서로 다른 VgControllerClient 를 생성해야 합니다.
이전 버전과의 호환성을 위해 (v0.5이하) new VgControllerClient() 대신 new Kollus.VideogatewayController() 를 사용해도 정상적으로 작동합니다.
try-catch문의 Exception code list는 다음과 같습니다.

code	message	description

code	message	description
-1	*	PostMessage API exception code
-99	player type is not defined	Player type이 정의되지 않았습니다.
-99	player type must be one of v2, v3, v4 and flash	Player type이 유효한 값이 아닙니다.
-99	this browser does not support postMessage	브라우저가 PostMessage API를 지원하지 않습니 다
-99	listener is not callable	이벤트 리스너가 함수형이 아닙니다.

CDN

Vg-Controller Client Library를 CDN으로 제공합니다. 가장 최신 버전의 라이브러리를 사용하시려면 아래 링크를 삽입하시면 됩니다

https://file.kollus.com/vgcontroller/vg-controller-client.latest.min.js

이전 버전의 라이브러리를 사용하시려면 latest 대신 버전명으로 변경하여 호출하시면 됩니다.

https://file.kollus.com/vgcontroller/vg-controller-client.1.1.4.min.js

Integrity 속성을 사용하면 VG-Controller Client Library의 악의적인 스크립트 변조를 방지할 수 있습니다. 스크립트 호출시 버전에 맞는 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 속성값은 여기를 참고하세요.

이벤트 리스닝

플레이어로부터 수신되는 각종 이벤트 발생시 사용자가 정의한 callback 함수를 실행하도록 이벤트 리스너(Event Listener)를 등록하는 방법입니다.

controller.on('event_name', function(param) {
  // 이벤트 리스너
});

하나의 이벤트에 하나 이상의 리스너를 등록할 수도 있습니다. 이 경우 이벤트 발생시에 등록된 모든 리스너가 실행됩니다

controller.on('event_name', function(param) {
  // 첫번째 리스너
});
controller.on('event_name', function(param) {
  // 두번째 리스너
});
// 이벤트 발생시 첫번째, 두번째 리스너가 모두 실행
// 다만, 자바스크립트 이벤트 루프와 callback 함수가 실행되는 방식에 의해, 첫번째 리스너가 반드시 먼저
// 실행된다고 보장할 수 없으며, 두번째 리스너가 실행되는 것이 첫번째 리스너가 실행된 뒤인 것도 아닙니다.

이벤트 리스너를 등록하는 함수인 on 은 메소드 체이닝(Method chaining)을 지원합니다.

controller.on('event_name_1', function(param) {
  // 첫번째 리스너
}).on('event_name_2', function(param) {
  // 두번째 리스너
});

하나 이상의 리스너를 등록한 경우 이벤트 발생시에 등록된 모든 리스너가 실행됩니다. 다만, 자바스크립트 이벤트 루프와 callback 함수가 실행되는 방식에 의해, 실행 순서가 바뀔 수 있습니다.

이벤트 목록

이벤트 목록
loaded	플레이어 로딩이 완료되면 이벤트가 발생합니다.	v3, v4
ready	플레이어 로딩이 끝나고 재생 정보를 서버로부터 획득하였으며, 실제 재생준비가 완료된 시점입니다.	v3, v4
play	재생 시작시에 발생합니다. 초기 재생 시작을 제외하고 일시 멈춤 상태에서 다시 재생을 시작할때도 발생합니다.	v3, v4
progress	재생시 매초마다 발생합니다. 단, HTML5 Video Player의 구조상 progress 이벤트가 정확하게 1초마다 발생하지 않을수 있습니다. (0.1에서 최대 0.5초 가량 차이가 날 수도 있습니다.) progress 이벤트로 작업하실 경우 이 부분을 유념하여 주십시요. Parameters: percent Integer 진행 백분율입니다. 값의 범위는 0 <= percent <= 100 입니다. position Number 현재 재생중인 위치의 값입니다. 초단위입니다. (소숫점 5자리 까지) duration Number 동영상의 전체 재생 길이입니다. 초단위입니다. (소숫점 5자리 까지)	v3, v4	`controller.on('progress', function(percent, position, duration) { // 인자의 순서는 위와과 같습니다. });`
pause	일시 정지시에 발생합니다.	v3, v4
done	재생 완료시에 발생합니다. 재생 완료는 duration의 끝까지 모두 재생한 경우를 의미합니다.	v3, v4
muted	음소거 상태가 변경시 호출됩니다. (음소거시, 음소거 해제시 모두 발생) 다만, V2 Player의 경우 현재 muted 이벤트를 제공하지 않습니다. 대신 음소거가 되는 경우 volumechange 이벤트가 발생되고 변경된 음량을 0으로 제공합니다. Parameters: is_muted Boolean true면 음소거, false면 음소거 해제입니다.	v3, v4	`controller.on('muted', function(is_muted) { // is_muted가 true면 음소거, false면 해제입니다. });`
seeking	플레이 시점 변경시 호출됩니다.	v4
seeked	플레이 시점 변경이 끝났을 때 호출됩니다.	v4
seek_start	플레이 시점 변경 시작시 호출됩니다	V4 V5
screenchange	전체, 일반화면 변경시 발생합니다. screen 파라미터는 windowed, fullscreen 2가지 문자열 가운데 하나를 제공합니다. Parameters: screen String windowed는 일반화면, fullscreen은 전체화면입니다.	v3, v4	`controller.on('screenchange', function(screen) { // ... });`
subtitle_load_done	자막의 로드가 완료되면 발생합니다
volumechange	음량 변경시 발생합니다. Parameters: volume Integer변경된 음량입니다. 범위는 0 <= volume <= 100 입니다.	v3, v4	`controller.on('volumechange', function(volume) { // volume의 범위는 0 <= volume <= 100 입니다. });`
speedchange	배속 변경시 발생합니다. 배속 최대값은 Player의 설정에 따라 바뀔 수 있습니다. Parameters: speed String변경된 배속입니다. 범위는 0.5 <= speed <= 4 입니다. Javascript 언어 특성상 2.0은 2로 표기 되기 때문에, Integer형 대신에 String형을 사용해 제공합니다.	v3, v4	`controller.on('speedchange', function(speed) { // speed의 범위는 0.5 <= speed <= 4 입니다. });`
playbackrateschange	배속 단위를 설정하는 배속값 그룹 변경시 발생합니다. Parameters: playback_rates String변경된 배속값 그룹의 문자열 입니다. 단일배열 : 배속값 메뉴가 한줄로 나열됩니다. ex) [1, 2, 3] 이중배열 : 배속값 메뉴가 여러줄로 나열될 수 있습니다. ex) [[0.5, 1, 1.5, 2], 2]	v3, v4	`controller.on('playbackrateschange', function(playback_rates) { // playback_rates는 배열의 문자열이며, //단일배열 또는 이중배열로 반환됩니다. });`
videosettingchange	비디오 속성 변경시 발생합니다. 비디오 속성 변경 기능은 V2 Player에만 존재하는 기능입니다. 다른 Player에서는 이벤트를 발생시키지 않습니다. 각 값의 범위는 모두 -50 <= value <= 50의 범위를 갖습니다. 사용자가 별도로 지정하지 않았을 경우 기본값은 0입 니다. Parameters: videosetting Objectbrightness(밝기), contrast(대비), saturation(채도)를 property로 갖는 object입니 다.	v3	`controller.on('videosettingchange', function(videosetting) { // videosetting 파라미터는 다음의 형태로 // 표시되는 Object 타입입니다. // // { // "brightness": 0, // "contrast": 0, // "saturation": 0 // } });`
jumpstepchange	ff, rw 메소드를 통해 이동할 시간값 변경시 발생합니다. Parameters: jumpstep Integer변경된 이동할 시간값입니다. 초단위입니다.	v3, v4	`controller.on('jumpstepchange', function(jumpstep) { // jumpstep은 초단위입니다. });`
subtitlevisibilitychange	자막의 화면출력 상태가 변경되면 발생합니다. Parameters: visible Boolean자막의 화면출력 여부 상태입니다	v3, v4
hlsfragchange	hls의 frag(2)가 변경되면 발생합니다.	v4
html5_video_supported	V3, V4 Player에서만 발생합니다. Player가 내부에서 HTML5 Video 재생기능을 사용할 수 있다고 판단하여 HTML5 Video Player를 로드할 경우엔 true 를, 전용 플레이어를 재생해야 한다고 판단할 경우엔 false를 리턴합니다. (http://caniuse.com/#feat=video 참조) Parameters: html5_video_supported BooleanPlayer가 HTML5 Player로 로드될 경우 true, 전용 플레이어로 로드될 경우는 false가 리턴됩니다.	v3, v4
error	Player가 재생오류를 반환하는 경우 발생합니다. Parameters: error_code IntegerKollus Player 에러 코드입니다.	v3, v4	`controller.on('error', function(error_code) { // ... });`
device_orientation_changed	모바일 디바이스인 경우 가로/세로 회전시 발생합니다. Parameters: orientation String세로 : Portrait, 가로 : Landscape	v4
hls_manifest_loaded	v4 player hls manifest 가 로드될 시 발생합니다. Parameters: data Object hls manifest data 객체입니다.	v4
dash_manifest_loaded	v4 player dash manifest 가 로드될 시 발생합니다. Parameters: data Object dash manifest data 객체입니다.	v4
bitrate_data_loaded	Hls/Dash manifest가 로드 된 후 Bitrate 데이터를 오름차순으로 정렬한 후 배열에 담아 반환합니다. Parameters: bitrate_data array Hls/Dash bitrate data object를 포함하는 배열 객체입니다.	v4	`controller.on('bitrate_data_loaded', function(bitrate_data) { // bitrate_data는 Bitrate Data Object를 포함하는 배열객체 입니다. // // [ // { // width: <int>, // height: <int>, // bitrate: <int> // } // ] });`
bookmark_change	v3 북마크 추가, 업데이트, 삭제시 발생합니다. Parameters: data String 북마크 변경 상태입니다.	V3	`controller.on('bookmark_change', function(data) { // 추가 add // 편집 update // 삭제 delete });`
waiting	재생중 waiting 이벤트가 발생될 때 1초마다 호출됩니다 Parameters: timeInteger 연속으로 발생된 waiting 시간값입니다. (단위 : 초)	V4
user_active_changed	플레이어 컨트롤바가 활성/비활성화 될 때 이벤트를 발생합니다. Parameters: activeBoolean 플레이어 컨트롤바 활성/비활성 여부 입니다.	V4
next_episode_auto_change	다음 회 자동재생 상태가 변경되면 발생합니다. next_episode_change 이벤트는 deprecated 되었습니다. v3/v4에서는 계속 사용 가능하나 권장하지 않습니다. Parameters: valueBoolean true면 다음 회 자동재생 사용, false면 다음 회 자동재생 사용 안함.	V3, V4, V5
next_episode_requested	다음 회차 Callback API가 호출되면 발생합니다. Parameters: valueBoolean true면 callback API 정상 호출, false면 callback API 호출 실패 또는 에러입니다.	V3, V4, V5
picture_in_picture_entered	PIP 모드 진입시 발생합니다. *브라우저에서 제공하는 자체 PIP 기능을 사용할 경우에는 발생하지 않습니다. (ex: FireFox 브라우저의 PIP 버튼 클릭)	V3 V4 V5
picture_in_picture_leaved	PIP 모드 종료시 발생합니다. *브라우저에서 제공하는 자체 PIP 기능을 사용할 경우에는 발생하지 않습니다. (ex: FireFox 브라우저의 PIP 버튼 클릭	V3 V4 V5

메소드 사용하기

Videogateway Controller Library가 지원하는 메소드를 호출하는 방법은 간단합니다.

controller.play();

이게 전부입니다. 경우에 따라서 파라미터를 요구하는 메소드도 있습니다.

controller.set_volume(90);

메소드 목록

이벤트 리스너 메소드

이벤트 리스너 메소드

on (event_name, callback_function)

이벤트 리스너를 등록합니다.

Parameters:

event_name Stringcallback function을 bind할 이벤트 이름입니다.
callback_function function이벤트 발생시 실행될 callback function입니다.
경우에 따라서 callback function에는 파라미터가 주어질 수 있습니다.

Return:

Object VG-Controller Client 객체를 반환합니다.

v3, v4

controller.on('event_name', function(param) {
// event_name에 해당하는 이벤트 발생시, 두번째 인자인 callback function 실행
});

off(event_name)

등록된 이벤트 리스너를 제거합니다.

Parameters:

event_name String callback function으로 bind된 이벤트 이름입니다.

Return:

Object VG-Controller Client 객체를 반환합니다.

v3, v4

controller.off('event_name');

재생 메소드

재생 메소드
get_progress()

V/G Controller

V/G Controller

개요

시작하기

VgControllerClient

아래 예시 코드를 영상이 보여질 html page에 적용하시면 됩니다.

CDN

이벤트 리스닝

loaded

ready

play

progress

Parameters:

pause

done

muted

volumechange

speedchange

videosettingchange

error

메소드 사용하기

메소드 목록

이벤트 리스너 메소드

이벤트 리스너 메소드

on (event_name, callback_function)

재생 메소드

재생 메소드

get_progress()