Version History

作成日	バージョン	備考
2016.05.03	v1.0	草案作成
2017.02.09	v1.1	seekable_end, disable_playrate 追加
2017.03.09	v1.2	live.url, live.poster_url 追加
2017.03.23	v1.3	title 追加
2017.06.26	v1.4	cdn, auth_type, use_ip_validation, use_kollus_token 追加
2017.09.06	v1.5	pc_skin 追加
2017.12.19	v1.6	Live spec にて kollus 認証追加
2018.02.08	v1.7	thumbnail 追加
2018.08.20	v1.8	subtitle_policy, drm_policy 追加 live jwt payload 項目追加
2018.10.29	v1.9	video_watermarking_code_policy 追加
2018.11.06	v1.10	play_section 追加
2019.01.07	v.1.11	video_watermarking_code_policy.enable_html5_player 追加
2019.03.06	v.1.12	live chatting option 追加, live payload key 追加及びlegacy処理
2019.07.11	v.1.13	Live spec にて video_watermarking_code_policy 追加
2019.07.18	v.1.14	disable_nscreen 追加
2019.09.20	v.1.15	live jwt にて play_expt 追加
2019.12.05	v.1.16	scroll_event 追加

概要

既存のKollusではMedia tokenは顧客がVideo gatewayにコンテンツ再生を要請する時、その内容を暗号化してURLの有効期限を設定するために使用されていました。ここでMedia tokenを使用するためにKollusから提供するモジュールをのサーバーに設置する必要があり、サーバーがモジュールに対応してない場合にはKollus APIを呼び出してMedia tokenを遠隔生成して使用したり、かつMedia tokenの仕様が変わる度にサーバーにモジュールを再度設置するなど、難点がありました。従って暗号学的に安全で具現が簡単なJSON Webtokenを利用してKollus モジュールに対する依存性を減らし、更に仕様変更により柔軟に対応ができるようにします。

注意事項

JWT Request

用語

セキュリティキー (Security Key)
- セキュリティキーは JWTをsigning するためにKollusと顧客だけが共有する秘密キーとなります。セキュリティキーは “設定 > サービスアカウント” ページから確認できます。この値は顧客の要望に応じて変更が可能であり、変更と同時に使用していたセキュリティキーは無効になります。従ってセキュリティキーは顧客のメンテナンス時間中などを利用して変更した方が好ましいです。
ユーザーキー (Custom Key)
- ユーザーキーは平文セキュリティキーを暗号化したものになります。JWTを使用して Videogatewayに要請する場合JWTと共に転送されなければなりません。

JWT生成方法

暗号化アルゴリズムはHMAC SHA256 (HS256)にして、Secret keyはセキュリティキー、Payloadには以下のPayload Specに合わせたJSON Stringを追加してJWTを生成します。

生成したJWTを使用してVideo gatewayに要請する方法

生成したJWTと使用者キーを以下のような形式のurlで生成して呼び出します。

http://v.jp.kollus.com/s?jwt=生成したJWT&custom_key=ユーザーキー

JWT Payload Spec

JWT Payload形式は以下のようなJSON文字列となります。

{
	"cuid": "CLIENT_USER_ID",
	"awtc": "AUDIO_WATERMARKING_CODE",
            "video_watermarking_code_policy": {
                       "code_kind":"client_user_id",
                       "font_size":7,
                      "font_color":"FFFFFF",
                      "show_time":1,
                      "hide_time":500,
                     "alpha":50,
                     "enable_html5_player": false,
            },
	"expt": EXPIRE_TIME,
	"pc_skin": {
		"skin_path": "http://file.kr.dev.kollus.com/public/custom/skin2.zip",
		"skin_sha1sum": "B2B688123F68BFA7DB4B1F89EC292C0835086D9B"
	},
	"mc": [{
		"mckey": "MEDIA_CONTENT_KEY",
		"mcpf": “MEDIA_CONTENT_PROFILE_KEY”,
		"tilte": "TITLE",
		"intr": IS_INTRO,
                   "scroll_event": SCROLL_EVENT,
		"seek": IS_SEEKABLE,
		"seekable_end": SEEKABLE_END,
		"disable_playrate": DISABLE_PLAYRATE,
                   “disable_nscreen”: DISABLE_NSCREEN,
                   "play_section": {
                              "start_time": PLAY_SECTION_START_TIME,
                              "end_time": PLAY_SECTION_END_TIME
                         }
                         "thumbnail": {
                             "enable": IS_ENABLE,
                             "thread": IS_THREAD,
                             "type": "TYPE"
                         },
                         "subtitle_policy" : {
                             "filter": {
                                 "name": "SUBTITLE_NAME",
                                 "language_code": "SUBTITLE_LANGUAGE_CODE",
                             },
                            "show_by_filter" : false,
                            "is_showable": true,
                         },
                         "drm_policy" : {
                             "kind" : "DRM_KIND",
                             "streaming_type": "hls",
                             "data" : "..."
                         },
						  "live": {
                       "url" : "LIVE_URL",
                       "poster_url" : "LIVE_POSTER",
                       "cdn": {
                           "type": "akamai",
                           "password": {
                               "short": "901490a9",
                               "long": "B2E2B80BCC848FB302EC55215C95E826"
                           }
                       },
                       "auth_type": "user",
                       "use_ip_validation": true,
                       "use_kollus_token": false
                   }
	}]
}

Payload 項目

名称	Datatype	必須有無	内容	Mediatype
cuid (CLIENT_USER_ID)	String	必須	コンテンツにアクセスする顧客のユーザーID: ブックマーク及びNScreenデータのKeyとして使用されます。(入力値は英語のみ対応) ※英語以外の値を入力する場合、キャプチャブロック及び重複再生ブロックなど、一部の機能で検索が制限される可能性があります。	VOD/LIVE
awtc (AUDIO_WATERMARKING_CODE)	String	選択 (基本値: null)	Kollus オーディオウォーターマーキング機能を実装するとき使用すウォーターマーキングコードで、APIを呼び出して獲得します。詳しい内容は技術担当者にお問い合わせください。使用しない場合にはEntryを削除するか、nullを入力します。	VOD
expt (EXPIRE_TIME)	Integer	必須	JWTの有効時間となり、Unix timestamp 形式で入力します。顧客側のサーバーとの時刻が一致しない場合があるため、有効時間が過ぎても最長1分以内まではアクセスができます。	VOD/LIVE
pc_skin (PC_EX_PLAYER_SKIN)	Array	選択	V2 PC PlayerのSkin(デザイン)を顧客が指定することができます。設定しない場合には省略できますが、このフィールドを追加した場合には必ず下位フィールドのskin_path, skin_sha1sumの正確な値を入力してください。	V2 Player
skin_path	String	選択	V2 PC PlayerのSkin情報が入っている圧縮ファイルのURL	V2 Player
skin_sha1sum	String	選択	V2 PC PlayerのSkin情報が入っている圧縮ファイルのsha1 checksum 値	V2 Player
mc	Array	必須	再生するコンテンツの再生情報が含まれたObjectタイプのEntryを配列として含まれている項目	VOD/LIVE
mckey (MEDIA_CONTENT_KEY)	String	必須	再生するコンテンツの識別キー。拡張Media content key形式も同一に使用可能	VOD/LIVE
mcpf (MEDIA_CONTENT_PROFILE_KEY)	String	選択 (基本値: null)	コンテンツの複数のプロファイルの中で一つのプロファイルを強制に指定して再生する場合に使用します。強制に指定するプロファイルキーを入力します。自動検出にするにはEntryを削除するか、 nullを入力	VOD
title (TITLE)	String	選択 (基本値: null)	コンテンツのタイトルを代替する文字列	VOD/LIVE
intr (IS_INTRO)	Boolean	選択 (基本値: false)	Introの有無を入力します。詳しくは下段の例示を参照してください。 Introがないコンテンツの場合にはEntryを削除するかまたはfalseを入力してください。	VOD
scroll_event	Boolean	(基本値: false)	画面の scroll event 適用有無 true: 画面の縦を基準でvideo領域を合わせて、見えない領域はscroll可能とする false: 既存の通りに横を基準で画面を合わせる	VOD
seek (IS_SEEKABLE)	Boolean	選択 (基本値: true)	コンテンツのseek可能の有無を入力します。introコンテンツの場合にはseek不可とします。 Seek可能とする場合にはEntryを削除するかまたはtrueを入力してください。	VOD
seekable_end (SEEKABLE_END)	Integer	選択 (基本値: -1)	Seek不可にした場合でも再生開始時点から入力した値の時点の間ではSeek可能になります。	VOD
disable_playrate (DISABLE_PLAYRATE)	Boolean	選択 (基本値: false)	倍速調整機能のOn/Offを設定	VOD
disable_nscreen (DISABLE_NSCREEN)	Boolean	選択 (基本値: false)	nscreen使用有無を設定	VOD
play_section.start_time	Integer	選択 (基本値: null)	リピート開始時点を設定 (単位: 秒)	VOD
play_section.end_time	integer	選択 (基本値: null)	リピート終了時点を設定 (単位: 秒)	VOD
thumbnail.enable	Boolean	選択 (基本値: true)	サムネール有効化有無を設定: Androidのみ対応	Android Player App/SDK
thumbnail.thread	Boolean	選択 (基本値: false)	スレッド方式の有無を設定: Androidのみ対応	Android Player App/SDK
thumbnail.type	String	選択 (基本値: null)	サムネールサイズを設定 (big / small): Androidのみ対応	Android Player App/SDK
subtitle_policy.filter.name	String	選択 (基本値: null)	字幕フィルターに字幕名を使用show_by_filter: trueに設定することが前提	VOD
subtitle_policy.filter.language_code	String	選択 (基本値: null)	字幕フィルターに言語コードを使用show_by_filter: trueに設定することが前提	VOD
subtitle_policy.show_by_filter	Boolean	選択 (基本値: false)	字幕ポリシーフィルターとの合致有無を識別	VOD
subtitle_policy.is_showable	Boolean	選択 (基本値: true)	字幕表示有無を識別	VOD
drm_policy.kind	String	選択 (基本値: null)	drm タイプを指定: 現状指定可能なDRMは"inka" ("inka"を使用する場合 third_party_infoの"cid"を "skb_kollus"に設定)	VOD
drm_policy.streaming_type	String	選択 (基本値: null)	ストリーミング方式をhls, dashに制限: "inka"にした場合ストリーミング方式を指定	VOD
drm_policy.data	Object	選択 (基本値: null)	DRM 認証データをオブジェクト(json) 方式で挿入 ex) { "license_url": "https://tokyo.pallycon.com/ri/licenseManager.do", "certificate_url": "https://license.pallycon.com/ri/fpsKeyManager.do?siteId=XXXX", "custom_header": { "key": "pallycon-customdata-v2", "value": "eyJ0aW1lc3RhbXAiOiI5OTk5LTEyLTMxVDIzOjU5....cl9pZCI6bnVsbCwiY2lkIjoidGVzdCJ9" } }
live.url (LIVE_URL)	String	選択 (基本値: null)	ライブストリーミングを再生するアドレスを入力	LIVE
live.poster_url (LIVE_POSTER)	String	選択 (基本値: null)	ライブストリーミングのポスターイメージのアドレスを入力	LIVE
live.cdn	Object	選択	CDNを使用しない場合、JSONブロックを省略します。	LIVE
live.cdn.type	String	必須	Kollusに定義されているCDN Type (使用可能タイプ: akamai)	LIVE
live.cdn.password	Object	選択 (基本値: 空白の文字列)	CDN アクセスのパスワード　※short, long 両方とも必要	LIVE
live.auth_type	String	選択 (基本値: user)	Edge 認証タイプ	LIVE
live.use_ip_validation	Boolean	選択 (基本値: false)	EdgeのMedia URLを生成する際にIP認証の使用有無	LIVE
live.use_kollus_token	Boolean	選択 (基本値: false)	EdgeのMedia URLを生成する際にKollus Token (ktn パラメータ)の使用有無	LIVE
video_watermarking_code_policy.code_kind	String	選択	"client_user_id"以外のStringの場合、そのまま表示
video_watermarking_code_policy.alpha	Integer	選択 (基本値: 200)	ビデオウォーターマーキングコードのalpha値を定義 (16進数 0~255)
video_watermarking_code_policy.font_size	Integer	選択 (基本値: 7)	ビデオウォーターマーキングコードのfont-size値を定義 (単位: px)
video_watermarking_code_policy.font_color	String	選択 (基本値; 'FFFFFF')	ビデオウォーターマーキングコードのfont-color値を定義
video_watermarking_code_policy.show_time	Integer	選択 (基本値;1)	ビデオウォーターマーキングコードの表示時間 (単位: 秒)
video_watermarking_code_policy.hide_time	Integer	選択 (基本値;60)	ビデオウォーターマーキングコードが表示されてから非表示になるまでの時間 (単位: 秒)
video_watermarking_code_policy.enable_html5_player	Boolean	選択 (基本値: false)	ビデオウォーターマーキングコードのHTML5 Player使用有無

例示

コンテンツの再生に使用するJWT Payload

catenoid というIDを持つユーザーがMedia content key “vnCVPVyV”を再生する場合

{
	"cuid": "catenoid",
	"expt": 1462931880,
	"mc": [{
		"mckey": "vnCVPVyV"
	}]
}

introありのコンテンツの再生に使用するJWT Payload

catenoid というIDを持つユーザーがintroでMedia content key “gDV2B1ZG”をseek 不可の状態で、本コンテンツは “vnCVPVyV”を再生する場合

{
	"cuid": "catenoid",
	"expt": 1462931880,
	"mc": [{
		"mckey": "gDV2B1ZG",
		"intr": true,
		"seek": false,
	},{
		"mckey": "vnCVPVyV"
	}]
}

Skip無効のコンテンツを再生するとき指定した時点まではSkipを許可するためのJWT Payload

catenoid というIDの使用者がintroでMedia contents key 「gDV2B1ZG」をseek 無効になっている状態で、開始から30秒まではSkipを許可する場合

{
	"cuid": "catenoid",
	"expt": 1462931880,
	"mc": [{
		"mckey": "gDV2B1ZG",
		"intr": true,
		"seek": false,
		"seekable_end": 30,
	}]
}

コンテンツの一部だけを再生させるためのJWT Payload

catenoid というIDの使用者がMedia contents key「vnCVPVyV」を60秒間再生をさせる場合

{
	"cuid": "catenoid",
	"expt": 1462931880,
	"mc": [{
		"mckey": "vnCVPVy",
		"play_section": {
			"start_time": 0,
			"end_time": 60,
	}]
}

Live(in VOD) JWT Payload Spec

Payload 項目

名称	Datatype	必須有無	内容	cdn type
cuid (CLIENT_USER_ID)	String	必須	コンテンツにアクセスする顧客のユーザーID: ブックマーク及びNScreenデータのKeyとして使用されます。	akamai kollus
expt (EXPIRE_TIME)	Integer	必須	JWTの有効時間となり、Unix timestamp 形式で入力します。顧客側のサーバーとの時刻が一致しない場合があるため、有効時間が過ぎても最長1分以内まではアクセスができます。	akamai kollus
mckey (MEDIA_CONTENT_KEY)	String	必須	再生するコンテンツの識別キー。ライブコンテンツの場合、VGマッピングに使用されます。アップロードされたコンテンツではなく、JWTのlive.urlでリターンされたコンテンツを再生する。	akamai kollus
title (TITLE)	String	選択 (基本値: null)	コンテンツのタイトルを代替する文字列	akamai kollus
live.url (LIVE_URL)	String	選択 (基本値: null)	ライブストリーミングを再生するアドレスを入力	akamai kollus
live.cdn	Object	選択	CDNを使用しない場合、JSONブロックを省略します。	akamai kollus
live.cdn.type	String	必須	Kollusに定義されているCDN Type (使用可能タイプ: akamai, kollus)	akamai kollus
live.cdn.password	Object	選択 (基本値: 空白の文字列)	CDN アクセスのパスワード　※short, long 両方とも必要	akamai
live.auth_type	String	選択 (基本値: user)	Edge 認証タイプ	akamai
live.use_ip_validation	Boolean	選択 (基本値: false)	EdgeのMedia URLを生成する際にIP認証の使用有無	akamai kollus
live.use_kollus_token	Boolean	選択 (基本値: false)	EdgeのMedia URLを生成する際にKollus Token (ktn パラメータ)の使用有無	akamai
live.use_duplication_block	Boolean	選択 (基本値: true)	重複再生遮断有無	kollus

例示

Live Streaming JWT Payload

ライブストリーミングの場合、intro / seek / playbackRate機能が無効になるため、該当JWTオプションは無意味

{
	"cuid": “catenoid”,
	"expt": 1462931880,
	"mc": [{
		"mckey": “gDV2B1ZG“,
		"title": “Live Sample“,
                         "live" : {
                                  "url": "http://XXXXX/XXX.m3u8",
                                  "poster_url": "http://XXXXX/XXX.jpg"
                         },
	}]
}

Live Streaming JWT Payload + Akamai CDN 認証

ライブストリーミングの場合、intro / seek / playbackRate機能が無効になるため、該当JWTオプションは無意味

{
  "mc": [
    {
      "mckey": "gDV2B1ZG",
      "live": {
        "url": "http://XXXXX/XXX.m3u8",
        "poster_url": "http://XXXXX/XXX.jpg",
        "cdn": {
           "type": "akamai",
           "password": {
              "short": "000000a0",
              "long": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
           },
           "auth_type": "user",
           "use_ip_validation": true,
           "use_kollus_token": false
        }
      },
      "title": "Live Sample"
    }
  ],
  "cuid": "test",
  "expt": 1462931880
}

Live Streaming JWT Payload + Kollus 認証

ライブストリーミングの場合、intro / seek / playbackRate機能が無効になるため、該当JWTオプションは無意味

{
  "mc": [
    {
      "mckey": "gDV2B1ZG",
      "live": {
        "url": "http://XXXXX/XXX.m3u8",
        "poster_url": "http://XXXXX/XXX.jpg",
        "cdn": {
           "type": "kollus",
           "use_ip_validation": true,
           "use_duplication_block": false
        }
      },
      "title": "Kollus Live"
    }
  ],
  "cuid": "test",
  "expt": 1462931880
}

※ exptフィールドの値は onetime URLの expire timeとなり、同時にライブストリームのexpire timeとして使用されます。例えば1時間のライブ配信をする場合にはexptの値を1時間以降の値に設定しなければなりません。

Live Streaming JWT Payload + Kollus 認証

Kollus Live 用のJWT SPECとなります。JWT Payload形式は以下のようなJSON文字列となります。

{
    "client_user_id": "CLIENT_USER_ID",
    "client_user_name": "CLIENT_USER_NAME",
    "video_watermarking_code_policy": {
                "code_kind":"client_user_id",
                "font_size":7,
                "font_color":"FFFFFF",
                "show_time":1,
                "hide_time":500,
                "alpha":50,
                "enable_html5_player": false
      },
    "client_user_image": "CLIENT_USER_IMAGE",
    "expire_time": EXPIRE_TIME,
    "play_expt": PLAY_EXPT_TIME,
    "live_media_channel_key": "LIVE_MEDIA_CHANNEL_KEY",
    "live_media_profile_key": "LIVE_MEDIA_PROFILE_KEY",
    "title": "TITLE",
    "chatting_policy": {
        "is_visible": true,
        "is_admin": false,
        "position": "right"
    }
}

Payload 項目

名称	Datatype	必須有無	内容	비고
client_user_id (or cuid)	String	必須	コンテンツにアクセスする顧客のユーザーID: ブックマーク及びNScreenデータのKeyとして使用されます。
client_user_name	String	選択	チャットを有効化した際に表示される名前として使用されます。
client_user_image	String	選択	チャットネームの横に表示されるイメージのURLとなり、httpsのみ対応
expire_time(or expt)	Integer	必須	JWTの有効時間となり、Unix timestamp 形式で入力します。顧客側のサーバーとの時刻が一致しない場合があるため、有効時間が過ぎても最長1分以内まではアクセスができます。
play_expt	Integer	選択 (基本値: 原罪時刻 + 48時間)	edgeにリクエストしたときにリターンされるexpire time
live_media_channel_key (or lmckey)	String	必須	再生するコンテンツの識別キー、拡張ライブメディアチャンネルキー形式も同様に使用可能
live_media_profile_key(or lmpf)	String	選択 (基本値: null)	ライブチャンネルのプロファイルの中で一つを指定して再生する場合に使用します。指定するプロファイルキーを入力します。自動選択するには該当Entryを削除するか、nullを入力します。指定がない場合、ABRで動作します。
title (TITLE)	String	選択 (基本値: null)	コンテンツのタイトルを代替する文字列
chatting_policy.is_visible	boolean	選択 (基本値: true)	チャットウィンドウの表示有無を指定
chatting_policy.is_admin	boolean	選択 (基本値: false)	チャットウィンドウの管理者かどうかを指定
chatting_policy.position	string	選択 (基本値: bottom)	チャットウィンドウの位置を指定 bottom \| left \| right
video_watermaking_code_policy.code_kind	String	選択	現在の仕様では使用する場合必須入力 "client_user_id"
video_watermaking_code_policy.alpha	Integer	選択(基本値: 200)	ビデオウォーターマーキングコードのalpha値を定義します。 (16陣数 0~255)
video_watermaking_code_policy.font_size	Integer	選択(基本値: 7)	ビデオウォーターマーキングコードのfont-size値を定義 (単位: px)
video_watermaking_code_policy.font_color	String	選択(基本値; 'FFFFFF')	ビデオウォーターマーキングコードのfont-color値を定義
video_watermaking_code_policy.show_time	Integer	選択(基本値;1)	ビデオウォーターマーキングコードの表示時間 (単位: 秒)
video_watermaking_code_policy.hide_time	Integer	選択(基本値;60)	ビデオウォーターマーキングコードが表示されてから非表示になるまでの時間 (単位: 秒)
video_watermaking_code_policy.enable_html5_player	Boolean	選択(基本値:false)	ビデオウォーターマーキングコードのHTML5 Player使用有無

サンプルコード

Json Web Tokens – Java

Json Web Tokens – ruby

Json Web Tokens – php

Download

サンプルコード

Download – jsp

Download – php

Download – dotnet

Browser not supported