Versions Compared

Old Version 2

changes.mady.by.user jpteam (Unlicensed)

Saved on

compared with

New Version 3

changes.mady.by.user jpteam (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

概要

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과 같음DATAのruntimeと同一
  • {SHOW_TIME}
    • JSON_DATA의 showtime과 같음DATAのshowtimeと同一
  • {USERVALUE0}~{USERVALUE9}
    • Video-gateway호출에 추가된 추가 정보 입니다.gateway呼出に追加された情報
    • ex) LCD={USERVALUE0}&UCD={USERVALUE4}
    • 영문,숫자 이외의 한글등의 문자열을 전달할 경우 웹 브라우저들의 차이점이 있기 때문에 해당 변수 전달시 UTF-8로 전달해야 합니다. (전달되는 문자열은 웹의 특성상 UrlEncode해서 전달해야 합니다.ブラウザ別に仕様が異なるため、ローマ字・数字以外の文字列を転送する場合にはUTF-8で転送してください。(転送する文字列はUrlEncodeをしてください。)
  • {TIMEMAP_DATA}
    • real_playtime  데이터를 초단위로 bitmap 방식으로 표시playtime データを秒単位のbitmap方式で表示
      • 1: 사용자가 시청한 구간ユーザーが視聴した区間 (초秒)
      • 2: 사용자가 시청하지 않은 구간(초ユーザーが視聴していない区間 (秒)
      • 예例) 000111100 ... : 4~7초는 사용자가 시청한 구간4~7秒はユーザーが視聴した区間を意味します。
  • {JSON_DATA}
    • 데이터 포멧データのフォーマット: JSON모든
    • 재생 정보를 포함한 데이터全ての再生情報が含まれたデータ

{PLAY_BLOCK_JSON}

  • {JSON_DATA}의 block_info 항목과 동일합니다.のblock_info項目と同一
  • block_info Object의 하위 노드를 포함합니다.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배속으로 재생한 경우 20초로 계산됩니다.
      • 모든 재생 시간을 포함한 시간입니다. (구간반복을 한 경우는 제외됩니다.実際の全体再生時間(単位：秒)
      • 倍速が適用された場合、倍速時間も計上されます。
      • 10秒間 2倍速で再生した場合、Play Timeは20秒
      • 全ての再生時間が計上されます。(リピート再生は集計されません。)
    • playtime : 컨텐츠 재생 시간コンテンツの再生時間
    • playtime_percent : duration에 대한 전체 재생 비율duration対比全体再生比率
    • start_at : Video-gateway를 호출한 시점의 Unixtimestamp 입니다. 다운로드 컨텐츠의 경우 start_at은 컨텐츠 재생시 단말의 unixtimestamp 입니다.gatewayをリクエストした時点のUnixtimestampとなります。ダウンロードしたコンテンツの場合、start_atはコンテンツを再生したデバイスのunixtimestampが適用されます。
    • last_play_at : 마지막 재생 위치 最終再生時点 (단위単位: 초秒)
    • runtime : 플레이어 실제 구동 시간(단위:초Playerの実際稼働時間 (単位:秒)
    • showtime:   플레이어를 실제적으로 play 한 구동 시간 (단위:초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이상으로 표시됩니다.ブロックを繰り返して再生する場合、100％以上に表示されます。
      • p2 : block_period 만큼 반복됩니다.分だけ繰り返されます
    • sessions : 사용자 블럭 재생을 시간별로 관리하는 항목 (배열) 세션 데이터는 이전 데이터를 모두 누적으로 전송합니다.ブロック再生を時間別に管理する項目 (配列)セッションデータは以前のデータまで累積されて転送されます。
      • block : 블럭 인덱스 ブロックインデックス (0부터 시작0から開始)
      • start_time : 해당 블럭을 시작한 시간 該当ブロックを開始した時刻 (unixtimestamp-localtime)
      • play_time : 해당 블럭 재생 시간該当ブロックの再生時間

  • uservalues : 사용자 정의 변수, 각 변수의 전체 합은 1KB를 넘지 않도록 해야 합니다. ユーザ定義条件、全ての条件の合計用量は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이 필요한 채널 마다 설정해야 합니다.

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

  • Callback URLs: 캐리지 리턴으로 각각 치환자를 포함한 URL을 등록합니다.재생정보를 다수의 시스템에서 전달 받을 수 있도록 캐리지리턴 キャリッジリターン(\n)으로 구분된 다수의 callback_url 을 등록할 수 있습니다.Kollus 플랫폼의 필요에 따라 URL 설정 수를 제한할 수 있습니다.を使用してそれぞれの置換値を含むURLを登録します。
    • 複数のシステムに再生情報を転送する場合はキャリッジリターンを使用して複数のcall_back_urlを登録することができます。
    • Kollus側の状況によって設定できるURLの数が制限される可能性があります。
  • Format: [block_count]:[period]:[enable_sessions]:[callback_url]
    • 구분자 区切り文字 : (콜론コロン)
    • block_count
      • 컨텐츠 재생 구간을 나누는 블럭의 수 입니다. 10으로 설정하면 컨텐츠의 길이가 300초의 경우 각 블럭은 30초로 구성됩니다.コンテンツの再生区間を分けるブロックの数です。コンテンツの長さが300秒の場合、10に設定すると各ブロックの長さは30秒になります。
    • peroid
      • 데이터 전송 주기
      • Callback이 전송되는 주기로 지정된 period(단위:초) 마다 호출되고 프로그램(플레이어)이 종료될 때 추가로 호출 됩니다. 단, 플래시 플레이어의 경우는 플레이어 종료시 호출되지 않습니다.
      • 플레이를 일시정시 또는 정지했을 때 추가로 호출 됩니다.
      • 단위 :초データ(Callback)転送周期
      • 指定されたperiod(単位：秒) 毎に呼び出されて最後にPlayerが終了する際にもう一度呼出されます。※HTML5 Playerは終了時に呼出されません。
      • 再生を一時停止または中止した際にもう一度呼出されます。
      • 単位: 秒
    • enable_blocks
      • 1 이면 block_info 항목에 blocks 정보를 포함 시킵니다.
      • 0 이면 block_info 항목에 blocks 정보는 없습니다.1の場合、block_info項目にblocks情報が含まれます。
      • 0の場合、block_info項目にblocks情報は含まれません。
    • enable_sessions
      • 1 이면 block_info 항목에 sessions 정보를 포함 시킵니다.
      • 0 이면 block_info 항목에 sessions 정보는 없습니다.1の場合、block_info項目にsessions 情報が含まれます。
      • 0の場合、block_info項目にsessions 情報は含まれません。
    • callback_url
      • Callback Url 입니다. 컨텐츠를 재생하는 사용자 환경에서 전송하기 때문에 방화벽 환경을 고려하여 http, 80포트 사용을 권장합니다.URL: コンテンツを再生する視聴者環境によってファイアウォールが適用されている条件を想定し、http, 80ポートを使用することを推奨します。

Callback URLs

Code Block
languagejs
themeMidnight
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로 전달됩니다.再生情報を転送するオプションは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

Code Block
languagejs
themeMidnight
● 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을 넘을 수 없습니다. 最大100個まで設定できます。 (range: 1~100)
    • 100을 넘는 데이터가 입력되면 최대값 100으로 처리 됩니다.
    • 0으로 입력되는 경우 1로 처리 됩니다.
    모든 컨텐츠의 {DURATION}보다 작거나 같도록 {
    • 100を超えるデータが入力された場合、100で処理します。
    • 0に入力された場合は1で処理します。
  • {BLOCK_CNT}를 설정하는 것을 권장합니다. はコンテンツ全体の{DURATION}이 より少なくなるよう設定してください。{BLOCK_CNT}보다 작은 경우 아래와 같이 처리됩니다.が{DURATION}より多くなると以下のように処理されます。
    • {BLOCK_CNT}가 100일때 値が100、{DURATION}이 30이면 전송되는 블럭 정보는 30개로 조정됩니다.値が 30の場合：転送されるブロック情報は30個を超えません。

Callback

호출 주기

リクエスト周期 (Callback period)

  • Callback은 시스템에 설정된 Callback Url 정보의 period 설정에 따라 호출됩니다.
  • 플레이어가 일시정지, 정지를 하는 경우도 Callback이 호출됩니다.
  • 주기적으로 호출되는 동일한 사용자의 정보는 Callbackはシステムから設定したCallback URL情報のperiod設定値の通りに呼出されます。
  • Playerが一時停止・中止される場合にもCallbackが呼出されます。
  • 周期的に呼出される同一ユーザの情報は{START_AT}, {CLIENT_USER_ID}값으로 구분하여 마지막 정보를 확인할 수 있습니다.플래시 플레이어의 경우는 플레이어 종료시 호출되지 않습니다.値で区分して最新の情報が確認できます。
  • HTML5 Playerの場合、Playerが終了される時点にCallbackが呼出されません。

USERVALUE0 ~ USERVALUE9

사용시 주의 할 점특수문자(영문,숫자이외의 모든문자:한글,한자,일어등)는 반드시 UTF-8문자열을 UrlEncode된 상태로 전달되어야 합니다.

使用する際に注意点

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

crossdomain.xml

  • Flash Player 사용시 callback을 받을 서버(고객사)에는 crossdomain.xml 파일이 있어야 합니다.Playerの場合、callbackを受け取る側(顧客側サーバー)にcrossdomain.xmlファイルが必要となります。

    Code Block
    languagejs
    themeMidnight
    <?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 Single Player는 제외합니다.

    • Hash 생성 규칙은 아래와 같습니다.


    データセキュリティー

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

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

      Code Block
      languagejs
      themeMidnight
      hash_1 = md5 ( post-data ) 
hash_2 = md5 ( hash_1 + service_account ) ← + 문자文字含む 포함

hash_2값을 post data의 hash 파라메터의 값으로 전송합니다.
      전송되는 Post 데이터 예시
      2値をpost dataのhashパラメータ値で転送します。


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

      Code Block
      languagejs
      themeMidnight
      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