メインコンテンツまでスキップ

LMS Callback

お知らせ

このドキュメントは機械翻訳で作成された下書きであり、現在レビュー中です。機械翻訳の特性上、一部の内容が不正確であったり、韓国語の原文と異なる場合があります。より正確な情報については、韓国語のドキュメントをご参照ください。

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

主な特徴​

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

Callback 設定方法​

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

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)integerblock_info内のブロック情報の包含有無
  • 0: 含めない
  • 1: 含める
セッション情報を含める (enable_sessions)integerblock_info内のセッション情報の包含有無
  • 0: 含めない
  • 1: 含める
Callback URL (callback_url)stringLMS データを受信するお客様側のサーバーアドレス

plug-in option​

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

パラメータータイプ説明
json_dataJSONすべての再生情報を含む JSON オブジェクト
（user_info、content_info、block_infoを含む）
client_user_idstringユーザー ID（JWT 生成時に入力したclient_user_id）
start_atinteger転送リクエスト時刻（VideoGateway 呼び出し時点、Unix timestamp）
  • ダウンロードコンテンツは再生時点のデバイス時刻
play_timeinteger再生速度および区間リピートを含む累積再生時間(sec)
playtime_percentintegerコンテンツ全体の長さに対する再生比率（%、小数点切り捨て）
  • 例: 2 回再生 → 200%
last_play_atinteger最後の再生位置(sec)
durationintegerコンテンツ全体の長さ(sec)
media_content_keystringメディアコンテンツキー
encoding_profile_keystringエンコーディングプロファイルキー
block_cntinteger設定されたブロック数
play_block_jsonJSON全ブロック再生情報（json_data.block_infoと同一）
host_namestringコンテンツリンクリクエストドメイン
  • 例: catenoid.video.kr.kollus.com
player_idstringKollus Player 固有 ID
hashstringデータ改ざん防止用 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_keystringサービスアカウントキー（参考文書: 認証と主要キー）
client_user_idstringユーザー ID（JWT 生成時に入力したclient_user_id）
player_idstringKollus Player 固有 ID
hardware_idstringハードウェア ID
host_namestringコンテンツリクエストドメイン
devicestringデバイスモデル名

コンテンツ情報(content_info)​

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

ブロック情報(block_info)​

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

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​

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

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

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

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

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

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

フィールドタイプ説明
uservalue{0~99}stringカスタム変数（uservalue0〜uservalue99）
注意
  • サイズ制限: すべてのuservalue項目の合計サイズは 1KB 以下である必要があります。
  • エンコーディング: 日本語・特殊文字・スペースが含まれる場合、必ずその値を UTF-8 URL エンコード処理して送信してください。