LMS Callback

Owned by jpteam (Unlicensed)
Last updated: May 18, 2021
2 min read

概要

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から転送する再生関連情報は顧客の意見を反映して提供項目を決めています。

  • 再生終了時点
  • コンテンツの区間別の再生情報
  • ユーザ情報 (ユーザが識別できるID)
  • コンテンツ情報
  • デバイス情報 (視聴環境)
  • コンテンツ全体を按分して各ブロック別の情報を収集

Plugin option

  • {MAC}
    • Mac Address
    • ユーザの個人情報になるため収集を推奨しません。
    • ユーザの理解度によってMac Addressが任意変更できるケースがあり、Mobile Playerの場合にApp登録制限のため対応していません。
  • {IP} - RemoteAddressの問題のため対応していません。(サーバー側で確認してください。)
    • コンテンツを再生するデバイスのIP Address
    • ユーザの個人情報になるため収集を推奨しません。
    • ルーターを使用する環境で収集されたIP AddressはPrivate IP Addressになります。正確なIPを集計する場合CallbackがリターンされるWebサーバー側でRemote_Addressを確認する必要があります。
  • {CLIENT_USER_ID}
    • ユーザー(顧客サービス会員)のUser ID
    • MediaTokenを生成する際にパラメータとして入力されたユーザID情報と同一です。入力されたユーザIDはKollus側に保存されません。ユーザのユニーク性を識別する用途で使用されます。
  • {START_AT}
    • Video-gatewayをリクエストした時点のUnixtimestamp
    • コンテンツ再生中に複数の再生情報が転送される可能性があります。同一リクエストに同一{START_AT} 値が付与されるため、同時間に多数の再生件数が発生する場合Unixtimestampが重複されることがあります。
    • ダウンロードしたコンテンツの場合、start_atはコンテンツを再生したデバイスのunixtimestampが適用されます。
  • {BLOCK_CNT}
    • Kollus側で設定したブロックの数
    • 再生情報を指定したブロック数に分けて管理し、データを転送する際に追加することが可能です。
  • {PLAY_TIME}
    • 全体再生時間 (単位 : 秒)：累計
    • 倍速が適用された場合、倍速時間も計上されます。
    • 10秒間 2倍速で再生した場合、Play Timeは20秒に計算
    • 全ての再生時間が計上されます。(リピート、倍速再生など全ての再生時間含まれます。)
  • {PLAYTIME_PERCENT}
    • DURATION対比全体再生比率 (単位:%, 定数: 小数点以下切り捨て)
    • コンテンツを繰り返して2回見た場合には200%に計算されます。
  • {DURATION}
    • コンテンツの長さ (単位: 秒)
  • {MEDIA_CONTENT_KEY}
    • メディアコンテンツキー
  • {ENCODING_PROFILE_KEY}
    • エンコーディングプロファイルキー
  • {PLAY_BLOCK_JSON}
    • データのフォーマット: JSON
    • ブロックの再生情報
  • {BLOCK_PLAY_1}~{BLOCK_PLAY_##{BLOCK_CNT}}
    • ブロックの再生有無
    • 0: 再生してない (Skip)
    • 1: 該当ブロックを再生(再生時間が0秒を超過すると1に設定されます。)
  • {BLOCK_TIME_1} ~{BLOCK_TIME_##{BLOCK_CNT}}
    • 該当ブロックを再生した時間 (単位：秒)
    • Playerの倍速再生機能が動作した場合、倍速を適用した再生時間に計算されます。
    • ブロック単位が3秒にした場合、ブロックが2回再生されたらブロックの再生時間は6秒に計算されます。
    • {DURATION}が{BLOCK_CNT}より少ない場合、{BLOCK_TIME#}の合計は{DURATION}を超過することになります。(各ブロックの再生時間がミリ秒になった場合、切り上げて1秒に計算されます。)
  • {LAST_PLAY_AT}
    • 最終再生時点 (単位: 秒)
  • {HOST_NAME}
    • Video Gatewayがリクエストされたドメイン名
    • ex) catenoid.video.kr.kollus.com
  • {PLAYER_ID}
    • Kollus PlayerのユニークID
    • Kollus Security Playerをインストールした際に生成されたID
    • HTML5 Playerの場合kfp文字列を転送します。(ユニーク値)
  • {PLAY_STATUS}
    • Kollus Security Playerのみ対応 (HTML5 Player使用不可)
    • play: 再生中
    • pause: 再生停止 (一時停止)
    • stop: Playerウィンドウが閉じられた際
  • {RUN_TIME}
    • JSON_DATAのruntimeと同一
  • {SHOW_TIME}
    • JSON_DATAのshowtimeと同一
  • {USERVALUE0}~{USERVALUE9}
    • Video-gateway呼出に追加された情報
    • ex) LCD={USERVALUE0}&UCD={USERVALUE4}
    • ブラウザ別に仕様が異なるため、ローマ字・数字以外の文字列を転送する場合にはUTF-8で転送してください。(転送する文字列はUrlEncodeをしてください。)
  • {TIMEMAP_DATA}
    • real_playtime データを秒単位のbitmap方式で表示
      • 1: ユーザーが視聴した区間 (秒)
      • 2: ユーザーが視聴していない区間 (秒)
      • 例) 000111100 ... : 4~7秒はユーザーが視聴した区間を意味します。
  • {JSON_DATA}
    • データのフォーマット: JSON
    • 全ての再生情報が含まれたデータ

{PLAY_BLOCK_JSON}

  • {JSON_DATA}のblock_info項目と同一
  • block_info Objectのサブノードが含まれます。

{JSON_DATA}

  • user_info

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

  • content_info

    • duration : コンテンツの長さ
    • encoding_profile : エンコーディングプロファイル
    • media_content_key : メディアコンテンツキー
    • channel_key : チャンネルキー
    • real_playtime : 実際の全体再生時間(単位：秒)
      • 倍速が適用された場合、倍速時間も計上されます。
      • 10秒間 2倍速で再生した場合、Play Timeは20秒
      • 全ての再生時間が計上されます。(リピート再生は集計されません。)
    • playtime : コンテンツの再生時間
    • playtime_percent : duration対比全体再生比率
    • start_at : Video-gatewayをリクエストした時点のUnixtimestampとなります。ダウンロードしたコンテンツの場合、start_atはコンテンツを再生したデバイスのunixtimestampが適用されます。
    • last_play_at : 最終再生時点 (単位: 秒)
    • runtime : Playerの実際稼働時間 (単位:秒)
    • showtime: Playerが実際に再生動作を行った時間 (単位:秒)

  • block_info

    • block_count : ブロック回数
    • blocks: マイルストーン (再生時間 単位: 秒)
      • b0 : ブロックの再生有無 (0:再生しない, 1:該当ブロック再生)
      • b1 : 0 ~ (int)
      • b2 : block_period 分だけ繰り返されます....
      • …
      • t0 : ブロック再生時間 (単位: 秒)
      • t1 : 0 ~ (int)
      • t2 : block_period 分だけ繰り返されます....
      • …
      • p0 : ブロックの再生比率 (単位: %)
      • p1 : 0~ (int) , ブロックを繰り返して再生する場合、100％以上に表示されます。
      • p2 : block_period 分だけ繰り返されます
    • sessions : ブロック再生を時間別に管理する項目 (配列)セッションデータは以前のデータまで累積されて転送されます。
      • block : ブロックインデックス (0から開始)
      • start_time : 該当ブロックを開始した時刻 (unixtimestamp-localtime)
      • play_time : 該当ブロックの再生時間

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

    • uservalue0
    • uservalue1
    • ....
    • uservalue9

Support options

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

OptionFlashPlayerKollusPlayer(PC)KollusPlayer(Monlie)
{MAC}XXX
{IP}XXX
{CLIENT_USER_ID}OOO
{START_AT}OOO
{BLOCK_CNT}OOO
{PLAY_TIME}OOO
{PLAYTIME_PERCENT}OOO
{DURATION}OOO
{MEDIA_CONTENT_KEY}OOO
{ENCODING_PROFILE_KEY}OOO
{PLAY_BLOCK_JSON}OOO
{BLOCK_PLAY_1} ~OOO
{BLOCK_TIME_1} ~OOO
{LAST_PLAY_AT}OOO
{HOST_NAME}OOO
{PLAYER_ID}X(kfp)OO
{PLAYLIST_SKIP}XOO
{USERVALUE0} ~OOO
{JSON_DATA}OOO

Settings

Callback設定の内容はチャンネル編集ページから確認できます。設定を申し込み・変更する際には担当までご連絡ください。

  • Callback URLs: キャリッジリターン(\n)を使用してそれぞれの置換値を含むURLを登録します。
    • 複数のシステムに再生情報を転送する場合はキャリッジリターンを使用して複数のcall_back_urlを登録することができます。
    • Kollus側の状況によって設定できるURLの数が制限される可能性があります。
  • Format: [block_count]:[period]:[enable_sessions]:[callback_url]
    • 区切り文字 : (コロン)
    • block_count
      • コンテンツの再生区間を分けるブロックの数です。コンテンツの長さが300秒の場合、10に設定すると各ブロックの長さは30秒になります。
    • peroid
      • データ(Callback)転送周期
      • 指定されたperiod(単位：秒) 毎に呼び出されて最後にPlayerが終了する際にもう一度転送されます。※HTML5 Playerの場合正常終了以外の時(ブラウザ閉じる・ページ移動など)には転送されません。
      • 再生を一時停止または中止した際にもう一度呼出されます。
      • 単位: 秒
    • enable_blocks
      • 1の場合、block_info項目にblocks情報が含まれます。
      • 0の場合、block_info項目にblocks情報は含まれません。
    • enable_sessions
      • 1の場合、block_info項目にsessions 情報が含まれます。
      • 0の場合、block_info項目にsessions 情報は含まれません。
    • callback_url
      • Callback URL: コンテンツを再生する視聴者環境によってファイアウォールが適用されている条件を想定し、http, 80ポートを使用することを推奨します。

Callback URLs

10:30:1:0:http://domain.com/check.asp?ip={IP}&id={CLIENT_USER_ID}&start={START_AT}&lms={
PLAY_BLOCK_JSON}&uservalue0={USERVALUE0}
20:180:0:1:http://another_domain.com/anohter_check.php?ip={IP}&id={CLIENT_USER_ID}&start={
START_AT}&lms={JSON_DATA}&uservalue0={USERVALUE0}

Plugin options

再生情報を転送するオプションはJSONフォーマットのArrayで転送されます。

  • progress_plugin (array)
    • http://domain.com/check.asp?block_period=10&ip={IP}&id={CLIENT_USER_ID}&start={START_AT}&json_data={JSON_DATA}&uservalue0={USERVALUE0}
    • http://another_domain.com/anohter_check.php?block_period=20&ip={IP}&id={CLIENT_USER_ID}&start={START_AT}&lms={PLAY_BLOCK_JSON}&uservalue0={USERVALUE0}

Callback data sample

● URL: http://lms.servicedomain.com/lms/register
● Method: POST
● Params:
    ● ID={CLIENT_USER_ID}
    ● MAC={MAC}
    ● LRN={USERVALUE0}
    ● LHF={USERVALUE1}
    ● IP={IP}
    ● LCD={USERVALUE2}
    ● TM={START_AT}
    ● PT={PLAY_TIME}
    ● ET={LAST_PLAT_AT}
    ● B1={BLOCK_PLAY_1}
    ● T1={BLOCK_TIME_1}
    ● ...
    ● SKIP={PLAYLIST_SKIP}
● http://lms.servicedomain.com/lms/register?ID=pobi&MAC=123456789ABCDEF&LRN=
123456789ABCDEF&LHF=1&IP=192.168.0.118&LCD=L123&UCD=U123&TM=12345678
9&PT=123456789&E T=123456789&SKIP=0&B1=1&B2=1&B3=1&B4=1&B5=1&B6=1&B7
=1&B8=1&B9=1&B10=1&T 1=123456789&T2=123456789&T3=123456789&T4=12345678
9&T5=123456789&T6=123456789&T7=123456789&T8=123456789&T9=123456789&T10
=123456789

Etc.

ブロック設定数制限 (Limit the number of blocks)

  • 最大100個まで設定できます。 (range: 1~100)
    • 100を超えるデータが入力された場合、100で処理します。
    • 0に入力された場合は1で処理します。
  • {BLOCK_CNT}はコンテンツ全体の{DURATION}より少なくなるよう設定してください。{BLOCK_CNT}が{DURATION}より多くなると以下のように処理されます。
    • {BLOCK_CNT}値が100、{DURATION}値が 30の場合：転送されるブロック情報は30個を超えません。

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

  • Callbackはシステムから設定したCallback URL情報のperiod設定値の通りに呼出されます。
  • Playerが一時停止・中止される場合にもCallbackが呼出されます。
  • 周期的に呼出される同一ユーザの情報は{START_AT}, {CLIENT_USER_ID}値で区分して最新の情報が確認できます。
  • HTML5 Playerの場合、Playerが正常に終了しない場合(ブラウザ閉じる・ページ移動など)にはCallbackが転送されない可能性があります。

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

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

crossdomain.xml

  • Flash Playerの場合、callbackを受け取る側(顧客側サーバー)にcrossdomain.xmlファイルが必要となります。

    <?xml version="1.0"?>
<!DOCTYPE cross-domain-policy SYSTEM
"http://www.adobe.com/xml/dtds/cross-domain-policy.dtd">
<cross-domain-policy>
    <site-control permitted-cross-domain-policies="master-only" />
    <allow-access-from domain="*" to-ports="*" />
    <allow-http-request-headers-from domain="*" headers="*" to-ports="*" />
</cross-domain-policy>

データセキュリティー

  • 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

Copyright © CATENOID, lnc. All Rights Reserved.
E-mail. jp_sales@catenoid.net | Tel. 03-4405-8462