概要

Kollusサービスで提供しているCallbackは、Platform CallbackとPlayer Callbackで分けていおり、ユーザーのコンテンツ利用情報を確認したい際にはPlayer Callbackが必要です。
Playerから取得された内容を指定したURLに転送する機能をLMS Callbackといいます。Playerは情報を一方転送するだけでレスポンスの受け取ることは出来ません。
この機能を使用する場合にはKollus Live管理画面から関連情報を設定する必要があります。LMS Callback URLの設定が終わりましたらVideo gatewayから再生関連情報が指定したURLに自動で転送されます。

Callback process

再生情報を受け取る流れを説明します。

1. Kollus 側で情報リクエストを設定します。
   • コンテンツ配信単位である"チャンネル"別に転送したい項目を指定することができます。
2. Video-gatewayが呼出すとコンテンツ再生に必要な情報をPlayerに転送し、この段階で再生と関わる情報の転送設定(1で設定したCallback設定情報)を共に転送します。
3. Playerは2.で指定された情報取得し、設定されたURL (顧客側) にを転送します。
4. コンテンツ再生に関する情報を取得するため、関連情報を収集します。
   • ユーザーの個人情報は収集されません。
   • Mac Address, IP Address 位置情報に関する内容は収集されません。

Customer Requirement

Kollusから転送する再生関連情報は顧客の意見を反映して提供項目を決めています。

● 視聴開始時間
● 視聴時間 (累計)
● 実際視聴時間
● ユーザー情報
● コンテンツ情報
● デバイス情報
● 転送周期

Plugin option

• {CLIENT_USER_ID}
  • ユーザー(顧客サービス会員)のUser ID
  • MediaTokenを生成する際にパラメータとして入力されたユーザID情報と同一です。入力されたユーザIDはKollus側に保存されません。ユーザのユニーク性を識別する用途で使用されます。
• {START_AT}
  • Video-gatewayをリクエストした時点のUnixtimestamp
  • コンテンツ再生中に複数の再生情報が転送される可能性があります。同一リクエストに同一{START_AT} 値が付与されるため、同時間に多数の再生件数が発生する場合Unixtimestampが重複されることがあります。
  • ダウンロードしたコンテンツの場合、start_atはコンテンツを再生したデバイスのunixtimestampが適用されます。
• {RUN_TIME}
  • 全体視聴時間 (単位: 秒)
  • 一時停止中の時間も合算されます。
• {MEDIA_CONTENT_KEY}
  • Kollus Live メディアコンテンツキー
• {ENCODING_PROFILE_KEY}
  • Kollus エンコーディングプロファイルキー
• {HOST_NAME}
  • VG linkがリクエストされたドメイン名
  • ex) catenoid.video.kr.kollus.com
• {PLAYER_ID}
  • Kollus PlayerのユニークID
  • Kollus Security Playerをインストールした際に生成されたID
• {PLAYLIST_STATUS}
• Kollus Security Playerのみ対応 (HTML5 Player使用不可)
• play: 再生中
• pause: 再生停止 (一時停止)
• stop: Playerウィンドウが閉じられた際
• {DEVICE}
• デバイスのモデル名
• {SHOW_TIME}
  • 実際に放送を視聴した時間の累計 (単位: 秒)  
  • 一時停止中の時間は合算されません。
  • 全ての再生時間が含まれます。(Time-shiftを行った分も累積されます。)
• {USERVALUE0}~{USERVALUE9}
  • Video-gateway呼出に追加された情報
  • ex) LCD={USERVALUE0}&UCD={USERVALUE4}
  • ブラウザ別に仕様が異なるため、ローマ字・数字以外の文字列を転送する場合にはUTF-8で転送してください。(転送する文字列はUrlEncodeをしてください。)
• {JSON_DATA}
  • データフォーマット: JSON
  • 全ての再生情報が含まれたデータ

{JSON_DATA}

• user_info

  • content_provider_key : 顧客 key
  • client_user_id : ユーザ(視聴者) ID
  • player_id : player ID
  • hardware_id : player hardware ID, 顧客確認用 (*Windowsのみ使用)
  • host_name : VG linkがリクエストされたドメイン名
  • device : デバイス名

• content_info

  • encoding_profile : エンコーディングプロファイル
  • media_content_key : メディアコンテンツキー
  • channel_key : チャンネルキー
  • start_at : Video-gatewayをリクエストした時点のUnixtimestamp, ダウンロードしたコンテンツの場合、start_atはコンテンツを再生したデバイスのunixtimestampが適用されます。
  • runtime : 現時刻 - 放送視聴開始時刻 (単位:秒) ex) 19:00 - 15:00 = 04:00　※Playerの実際稼働時間
  • showtime :  Playerが実際に再生動作を行った時間 (単位:秒)
    • 一時停止中の時間は合算されません。
    • 全ての再生時間が含まれます。(Time-shiftを行った分も累積されます。)

• uservalues : ユーザー定義の追加条件、全ての条件の合計用量を1KB未満にしてください。

  • uservalue0
  • uservalue1
  • ....
  • uservalue9

Support options

Player別の対応オプションを確認してください。{MAC}, {IP}は個人情報になるため必要な場合別途ご相談ください。

Settings

Callback設定はチャンネル編集ページから行えます。Callbackが必要なチャンネル別に全て設定してください。

• Callback URLs: キャリッジリターン(\n)を使用してそれぞれの置換値を含むURLを登録します。
  • 複数のシステムに再生情報を転送する場合はキャリッジリターンを使用して複数のcall_back_urlを登録することができます。
  • Kollus側の状況によって設定できるURLの数が制限される可能性があります。
• Format: [peroid]:[callback_url]
  • 区切り文字 : (コロン)
  • peroid
    • データ(Callback)転送周期
    • 指定されたperiod(単位：秒) 毎に呼び出されて最後にPlayerが終了する際にもう一度呼出されます。※Flash Playerは終了時には呼出されません。
    • 再生を一時停止または中止した際にもう一度呼出されます。
    • 単位: 秒
  • callback_url
    • Callback URL: コンテンツを再生する視聴者環境によってファイアウォールが適用されている条件を想定し、http, 80ポートを使用することを推奨します。

Callback URLs

30:http://domain.com/check.asp?id={CLIENT_USER_ID}&start={START_AT}&lms={JSON_DATA}
&uservalue0={USERVALUE0}

Callback data sample

● URL: http://lms.servicedomain.com/lms/register
● Method: POST
● Params:
	● ID={CLIENT_USER_ID}
	● LRN={USERVALUE0}
	● LHF={USERVALUE1}
	● LCD={USERVALUE2}
	● TM={START_AT}
	● RT={RUN_TIME}
● http://lms.servicedomain.com/lms/register?ID=pobi&LRN=123456789ABCDEF&LHF=1&LCD=L123&UCD=U123&TM=123456789&RT=123456789

Etc.

Callback リクエスト周期 (Callback period)

• Callbackはシステムから設定したCallback URL情報のperiod設定値の通りに呼出されます。
• Playerが一時停止・中止される場合にもCallbackが呼出されます。
• 周期的に呼出される同一ユーザの情報は{START_AT}, {CLIENT_USER_ID}値で区分して最新の情報が確認できます。
• HTML5 Playerの場合、Playerが終了される時点にCallbackが呼出されません。
• PC, Android, iOS Security playerの場合にも強制終了の際には呼出されません。

USERVALUE0 ~ USERVALUE9 使用する際に注意点

• 特殊文字 (ローマ字・数字以外の全ての文字一切)は必ずUTF-8文字列をUrlEncodeされた状態で転送しなければなりません。

データ保護

• LMS callbackデータの変更・偽造防止のためPOSTで転送される全ての情報に対してHashを生成し、転送されたHash値と一致することを確認してください。
  ※ Hash 生成方式に漏洩の可能性があるFlash Player, HTML5 Playerは対象外

• Hash生成規則は以下の通りになります。

  hash_1 = md5 ( post-data ) 
  hash_2 = md5 ( hash_1 + service_account ) ← + 文字含む 
  hash_2値をpost dataのhashパラメータ値で転送します。

• 転送されるPostデータのサンプル

  ID=pobi&MAC=123456789ABCDEF&LRN=123456789ABCDEF&LHF=1&IP=192.16 8.0.118&LCD=L123&UCD=U123&TM=123456789&PT=123456789&ET=123456789 &SKIP=0&B1=1&B2=1&B3=1&B4=1&B5=1&B6=1&B7=1&B8=1&B9=1&B10=1&T1= 123456789&T2=123456789&T3=123456789&T4=123456789&T5=123456789&T6=1 23456789&T7=123456789&T8=123456789&T9=123456789&T10=123456789&hash =7dec341ff384574f24c6c441b46bc9b1