Kollus VG Controller

*Latest version 1.2.4

概要

Kollus VG Controllerは、Videogatewayから提供されるメディアの一部のコントロールを顧客のウェブサイト内で実装できるようにサポートするJavaScriptライブラリです。Kollus VG Controllerには次の特徴があります。

  • Videogatewayで自動的に実行されるプレーヤータイプに関係なく、同じコードで制御できます。

  • 簡単なインストールと使い方

  • プレーヤーの検出や実行について心配する必要がありません。

  • サードパーティのJavaScriptライブラリは必要ありません。

メソッドとイベントリストの隣に表示されるV2、V3、V4 Playerなどは、該当のメソッドやイベントをサポートするプレーヤーを示します。

  • V2：通常、暗号化されたファイルはV2 Playerを介して再生されます。V2 Playerは、IEの場合はActiveX、ChromeまたはFirefoxの場合はNPAPIを使用するプレーヤーです。

  • V3：暗号化されたファイルがEdgeまたはChromeの45バージョン以上のウェブブラウザから呼び出される場合、ハイブリッドHTML5プレーヤーが実行されます。

  • V4：暗号化されていないファイルの場合、HTML5プレーヤーが実行されます。

  • 名前の横にプレーヤーが表示されない場合、それはすべてのプレーヤーが共通でその機能をサポートしていることを意味します。

VgControllerClient

(顧客の 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.jp..."></iframe>
</body>
...

  • VgControllerClient 生成の際にパラメータで転送するtarget_windowには、Webページに添付しているKollus Videogateway iframeのHTMLElementにcontentWindow属性を入力します。

  • このスクリプトはwindow.postMessage API を使ってPlayerとの通信を行うため、該当機能に対応していないブラウザでは動作しません。

  • Web Page内部に複数のiframeをembedしている場合、制御するiframe毎にVgControllerClient を生成する必要があります。

  • 以前バージョンとの互換性を考慮して(v0.5以前) new VgControllerClient()の代わりにnew Kollus.VideogatewayController()を使用しても正常に動作します。

  • try-catch文のException code listは以下のようになります。

codemessagedescription

-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属性値は 属性の値が必要な場合担当者にお問い合わせください。

VR Contents (Mobile Device)

iframe内で呼び出される360 VRコンテンツの場合、AndroidおよびiOSデバイスで再生時に問題が発生します。Androidの場合、Orientation値が正しく適用されず、左右の方向が逆になります。iOSの場合、iOS 13以降、DeviceMotion権限を取得する必要があり、Gyroscopeが正常に動作するようになりますが、この権限はiframe内で取得できないため、正常に動作しません（iOS 13以前のバージョンではSafari設定から 'Motion & Orientation Access'オプションを直接変更する必要があります）

これらの問題を解決するには、VG-Controller 1.1.10以降をインストールする必要があり、VG-ControllerクライアントからDeviceMotionイベントを自動的に登録して、VG-Controllerサーバーと通信します（外部のiframeイベントを定期的に内部に転送します）

OSの場合、Controller.set_vr_overlay()メソッドを実行する必要があります。詳細については、下記のリファレンスの「メソッドリスト」の「set_vr_overlayメソッド」をご参照ください。

Known Issue iOS 13.4 バージョンでは権限を取得しても DeviceMotionの rotationRate値が正常に発生しないエラーが報告されています。

Intent Scheme Call Bug (iframe in Android)

プレイヤーページがiframe内でVGを呼び出すように構成されている場合、一部のモバイルAndroidデバイスでは専用プレイヤー（Kollus Player App）が正しく実行されないことがあります。 （Androidデバイス環境では、Intent Schemeを使用して呼び出すように設定されていますが、Chromeブラウザの場合、‐iframeを使用すると正常に動作しないエラーが報告されています。） このような場合、VG-Controller 1.1.15以降を使用すると正常に動作します。

別途具現するコードはないので, VG-Controllerが環境を分析して自動分析し処理します。

イベントリスニング

Playerのイベントが発生した際に使用者が定義したcallback関数を実行するためのイベントリスナー(EventListener)を登録する方法となります。

controller.on('event_name', function(param) {
    // イベントリスナー
});

単一イベントに複数のリスナーを登録することができます。この場合、イベントが発生すると登録されている全てのリスナーが実行されます。

controller.on('event_name', function(param) {
    // 1番目のリスナー
});
controller.on('event_name', function(param) {
    // 2番目のリスナー
});

// イベント発生の際に1番目、2番目リスナーが全て実行
// 但し、JAVA Scriptイベントループとcallback関数の実行方式によって
// リスナーが順番通りに実行されない可能性があります。

イベントリスナーを登録する関数である「on」 はメソッドチェイニング(Method chaining)に対応しています。

controller.on('event_name_1', function(param) {
    // 1番目のリスナー
}).on('event_name_2', function(param) {
    // 2番目のリスナー
});

一つ以上のリスナーを登録した場合、イベント発生時に登録されたすべてのリスナーが実行されます、ただし、javascriptイベントループとcallback関数が実行する方法によって実行の順番が変わる可能性があります。

イベントリスト

イベントリスト

内容

プレイヤー

コード

loaded

プレイヤーのロードが完了すると、イベントが発生します

v3, v4

ready

プレイヤーのロードが終わり、再生情報をサーバーから取得し、実際の再生準備が完了した時点です

v3, v4

play

再生開始時に発生します。 初期再生開始を除き、一時停止状態で再再生を開始する場合も発生します。

v3, v4

progress

再生時に毎秒発生します。 ただし、HTML5 Video Playerの構造上、progressイベントが正確に1秒ごとに発生しないことがあります。 (0.1から最大0.5秒ほど差が出ることがあります。)progressイベントで実行する場合、この点に注意してください。

Parameters:

  • percent INTTERの進行パーセンテージです。 値の範囲は 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

ミュート状態が変更された場合に呼び出されます。 (音消去時、音消去解除時の両方発生)

Parameters:

  • is_muted BOOLEAN trueはミュート、falsはミュート解除

v3, v4

controller.on('muted', function(is_muted) { // is_mutedが trueの場合ミュート、falseの場合ミュート解除 });

seeking

再生時点変更時呼び出します。

v4

seeked

再生時点変 再生時点変更が終わった場合呼び出します。

v4

screenchange

全体、一般画面の変更時に発生します。 IE10 以下のブラウザの場合、enable_fullscreen_button()が 有効化されている状態であれば、fullscreenボタンをクリックすると、実際にfullscreen/windowed切り替えが行われませんが、screenchangeイベントは正常に返されます。 screenパラメータは、windowed、fullscreenの2つの文字列のうちの1つを提供します。

Parameters:

  • screen STRING windowedは一般画面、fullscreenは全体画面です。

v3, v4

controller.on('screenchange', function(screen) { // ... });

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が変更時に発生します。

v4

html5_video_supported

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> // } // ] });

メソッド使用

Videogateway Controller Libraryが対応するメソッドを呼び出す方法となります

controller.play();

上記の記載だけで呼び出すことができますが、場合によってはパラメーターが必要なメソッドもあります。

controller.set_volume(90);

メソッドリスト

＊メソッドリストについては左側はメソッドリストを参考してください。

PreviousScheme OptionNextイベントメソッド

Last updated