LMS Callback

Kollus VOD は、コンテンツ再生中に発生する視聴データをリアルタイムで収集し、お客様の学習管理システム(LMS)サーバーに送信する機能をサポートしています。 これにより、受講完了の判定、視聴パターンの分析、最後の視聴位置の保存など、高度な教育管理ロジックを実装できます。

主な特徴

• 非同期転送: プレイヤーはサーバーの応答を待たずにデータを送信するため、再生フローを妨げません。
• 自動再送ポリシー: お客様のサーバーまたはネットワーク障害が発生した場合、クライアントにデータを一時保存し、通信が復旧した時点で順次再送します。
• 個人情報保護: LMS Callback データには Mac Address、IP Address などの機密情報は含まれません。

Callback 設定方法

Callback URL は Kollus VOD コンソールで設定できます。

• 参考文書: Callback 連携 - LMS Callback

Callback フロー

LMS データ収集からお客様のサーバーへの転送までの全プロセスです。

1. Callback 設定: Kollus VOD コンソールでチャンネルごとの Callback URL および収集仕様を定義します。
2. 再生リクエスト: ユーザーがコンテンツをクリックすると、お客様のサーバーは VideoGateway を呼び出します。
3. 設定の受け渡し: VideoGateway がプレイヤーに再生情報、Callback ポリシー、カスタム変数（uservalue0〜uservalue99）を渡します。
4. リアルタイムデータ転送: プレイヤーが視聴データを収集し、お客様のエンドポイントに送信します。

Callback 呼び出しポリシー

LMS サーバーは受信したパラメーターを通じてユーザーの学習履歴を再構成する必要があるため、以下の転送ポリシーに従ってロジックを設計してください。

• 定期呼び出し: 設定された転送サイクル(period)ごとにデータを送信します。
• イベント呼び出し: 周期に関わらず、一時停止または再生終了時に即座にデータを送信します。
• 再送ポリシー: ネットワーク障害が発生した場合、クライアントにデータを一時保存し、通信復旧後すぐに再送します。

同一セッションデータの識別

転送サイクルおよびイベントにより、同一ユーザーの Callback データが複数回受信される場合があります。 システムはclient_user_id（ユーザー ID）とstart_at（セッション開始時刻）の値を組み合わせて、単一再生セッションの最新情報を判定し、データを更新する必要があります。

• 判定ロジック: client_user_idとstart_atが一致するレコードをグループ化した後、最も新しく受信したデータを最終視聴履歴として確定します。

データ算出仕様

LMS データの核心である再生進行率と再生時間の測定基準です。

再生ブロック(Block)

ブロックは全体の動画を均等に分割した論理的な単位です。プレイヤーは各ブロックの視聴有無を個別に記録して再生進行率を算出します。

項目	詳細仕様	備考
設定範囲	1〜100 の整数	100 を超える値を入力した場合、自動的に 100 に固定
最小単位	1（全体を単一ブロック）	0 以下の値を入力した場合、1 として処理
推奨設定	コンテンツ長さ以下に設定	1 秒あたり 1 ブロックを超えて生成されない

• 例 1: 300 秒の動画のブロック数を 10 に設定した場合、各ブロックの長さは 30 秒になります。
• 例 2: 30 秒の動画のブロック数を 100 に設定しても、実際には 1 秒あたり 1 個ずつ計算され、合計 30 個のブロックデータのみ生成・送信されます。

再生時間用語の定義

各指標の計算方法が異なるため、以下の表を参考にシステムを実装してください。

用語	再生速度	区間リピート	一時停止	例: 0〜10 秒再生区間、2 倍速、1 回リピート、5 秒一時停止
play_time	◯	◯	×	(10 秒 ÷ 2 倍速) + (10 秒リピート ÷ 2 倍速) = 10 秒
real_playtime	◯	×	×	(10 秒 ÷ 2 倍速) = 5 秒
runtime	×	◯	◯	10 秒 + 10 秒リピート + 5 秒一時停止 = 25 秒
showtime	×	◯	×	10 秒 + 10 秒リピート = 20 秒

Callback 設定情報

転送方式

• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Data Format: FormData

設定パラメーター

Kollus VOD コンソールで設定する基本 LMS ポリシーパラメーターです。

パラメーター	タイプ	説明
ブロック数 (block_count)	integer	動画を分割する論理的な区間数
転送サイクル (period)	integer	サーバーへデータを転送する時間間隔(sec)
ブロック情報を含める (enable_blocks)	integer	block_info内のブロック情報の包含有無 0: 含めない 1: 含める
セッション情報を含める (enable_sessions)	integer	block_info内のセッション情報の包含有無 0: 含めない 1: 含める
Callback URL (callback_url)	string	LMS データを受信するお客様側のサーバーアドレス

plug-in option

LMS Callback リクエスト時に一緒に送信される詳細項目を設定します。選択したオプションは Callback リクエストのパラメーターとして含まれます。

パラメーター	タイプ	説明
json_data	JSON	すべての再生情報を含む JSON オブジェクト （user_info、content_info、block_infoを含む）
client_user_id	string	ユーザー ID（JWT 生成時に入力したclient_user_id）
start_at	integer	転送リクエスト時刻（VideoGateway 呼び出し時点、Unix timestamp） ダウンロードコンテンツは再生時点のデバイス時刻
play_time	integer	再生速度および区間リピートを含む累積再生時間(sec)
playtime_percent	integer	コンテンツ全体の長さに対する再生比率（%、小数点切り捨て） 例: 2 回再生 → 200%
last_play_at	integer	最後の再生位置(sec)
duration	integer	コンテンツ全体の長さ(sec)
media_content_key	string	メディアコンテンツキー
encoding_profile_key	string	エンコーディングプロファイルキー
block_cnt	integer	設定されたブロック数
play_block_json	JSON	全ブロック再生情報（json_data.block_infoと同一）
host_name	string	コンテンツリンクリクエストドメイン 例: catenoid.video.jp.kollus.com
player_id	string	Kollus Player 固有 ID
hash	string	データ改ざん防止用 Hash 値（HTML5 Player は非対応）

Hash（整合性検証）生成ルール

データ改ざんを防ぐために、以下の手順に従って Hash 値を生成し、受信データの整合性を検証してください。

1. hash_1 = md5(post_data)
2. hash_2 = md5(hash_1+service_account)
3. 生成されたhash_2の値をリクエストパラメーターのhash値と比較して検証

参考

• +は算術演算ではなく、文字列結合(String Concatenation)を意味します。
• 以下の例のように、+記号そのものを文字列に含める必要があります。

Hash 生成例

hash_1 = "abc123"
service_account = "kollus-test"

hash_2 = md5("abc123+kollus-test")

LMS Callback データフォーマット

VideoGateway がプレイヤーに渡す Callback 設定の全フォーマットです。

[block_count]:[period]:[enable_blocks]:[enable_sessions]:[callback_url]?{PLUGIN_OPTION}

LMS Callback データ例

例 1（基本構成）

10:30:1:0:https://domain.com/check.asp?id={CLIENT_USER_ID}&start={START_AT}&uservalue0={USERVALUE0}

例 2（JSON データを含む）

20:180:0:1:https://another_domain.com/another_check.php?id={CLIENT_USER_ID}&start={START_AT}&json_data={JSON_DATA}&uservalue0={USERVALUE0}&uservalue1={USERVALUE1}

転送データ(JSON_DATA)の構造

JSON_DATAは再生情報の全体を含みます。

ユーザー情報(user_info)

フィールド	タイプ	説明
content_provider_key	string	サービスアカウントキー（参考文書: 認証と主要キー）
client_user_id	string	ユーザー ID（JWT 生成時に入力したclient_user_id）
player_id	string	Kollus Player 固有 ID
hardware_id	string	ハードウェア ID
host_name	string	コンテンツリクエストドメイン
device	string	デバイスモデル名

コンテンツ情報(content_info)

フィールド	タイプ	説明
duration	integer	コンテンツ全体の長さ(sec)
encoding_profile	string	エンコーディングプロファイルキー
media_content_key	string	メディアコンテンツキー
channel_key	string	コンテンツが登録されているチャンネルの識別キー
real_playtime	integer	再生速度を含み、区間リピートを除く累積再生時間(sec) 例: 0〜10 秒区間を 2 倍速再生 → 5 秒
playtime	integer	再生速度および区間リピートを含む累積再生時間(sec)
playtime_percent	integer	コンテンツ全体の長さに対する再生比率（%、小数点切り捨て） 例: 2 回再生 → 200%
start_at	integer	転送リクエスト時刻（VideoGateway 呼び出し時点、Unix timestamp） ダウンロードコンテンツは再生時点のデバイス時刻
last_play_at	integer	最後の再生位置(sec)
runtime	integer	区間リピートおよび一時停止を含む累積再生時間(sec)
showtime	integer	区間リピートを含む累積再生時間(sec)
serial	integer	LMS 送信順序（0 から順次増加）

ブロック情報(block_info)

フィールド	タイプ	説明
block_count	integer	動画を分割する論理的な区間数
blocks	object	ブロックごとの再生データ（マイルストーンベースのサマリー情報）
sessions	array	詳細再生セッション履歴（過去のセッションデータを含む累積データ配列）

block_info.blocks

各ブロックインデックス({n})を基準に詳細データを提供します。ブロックインデックスは 0 から始まり、block_countの数だけ繰り返されます。

フィールドパターン	タイプ	説明
b{n}	string	ブロック再生の有無 0: 再生していない 1: 再生済み
t{n}	string	再生速度を含むブロック再生時間(sec)
p{n}	string	ブロック再生比率（%、小数点切り捨て） 例: 2 回再生 → 200%

例

• b0=1, t0=15, p0=100 → ブロック 0 を合計 15 秒間視聴し、該当区間を 100%学習完了
• b1=0, t1=0, p1=0 → ブロック 1 は視聴履歴なし

block_info.sessions

フィールド	タイプ	説明	例
block	integer	このデータが含まれるブロックインデックス（0 から開始）
start_time	integer	セッションの再生開始時刻（Unix timestamp → localtime）
play_time	integer	セッションの再生時間(sec)

例

ブロック 0 を 1761531042 の時刻に再生開始し、1 秒間再生した場合の JSON 構造です。

[
    {
        "block": 0,
        "start_time": 1761531042,
        "play_time": 1
    }
]

プレイヤーステータス(player_status)

フィールド	タイプ	説明
playback_rate	integer	再生速度
volume_level	integer	音量レベル（0〜100）
play_status	string	再生状態（Kollus セキュアプレイヤーのみ使用可能） play: 再生中 pause: 一時停止 stop: 終了

カスタムフィールド(uservalues)

フィールド	タイプ	説明
uservalue{0~99}	string	カスタム変数（uservalue0〜uservalue99）

注意

• サイズ制限: すべてのuservalue項目の合計サイズは 1KB 以下である必要があります。
• エンコーディング: 日本語・特殊文字・スペースが含まれる場合、必ずその値を UTF-8 URL エンコード処理して送信してください。