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

統合 JWT 規格

このドキュメントは、非暗号化コンテンツ（一般コンテンツ）および Kollus DRM コンテンツの安全な再生とプレイヤー機能制御のための**統合 JWT(JSON Web Token)**の詳細規格を説明します。 単純な再生認証を超え、再生速度制限・コンテンツ公開区間設定・ウォーターマーキングなど、サービスポリシーに合わせた各種セキュリティおよび利便性機能をお客様のサーバーで直接定義できます。

JWT 技術仕様​

暗号化アルゴリズム​

Kollus VOD は HMAC SHA-256(HS256)アルゴリズムのみをサポートしています。

Header: { "alg": "HS256", "typ": "JWT" }

認証キー​

JWT 生成および呼び出し時に以下の 2 つのキーを使用します。

セキュリティーキー​

  • 説明: JWT 署名(Signing)および検証に使用される秘密鍵です。外部への漏洩にご注意ください。
  • 確認方法: Kollus VOD コンソール > [サービスアカウント] > [カスタムキー]
セキュリティーキーの変更

セキュリティーキーの変更については、営業担当者(jp_sales@catenoid.net)までお問い合わせください。

カスタムキー (custom_key)​

  • 説明: セキュリティーキーを暗号化した値で、セキュリティーキーとともに認証(JWT)に使用されます。
  • 確認方法: Kollus VOD コンソール > [サービスアカウント] > [カスタムキー]
    • ブラウザのリフレッシュ時に値が更新される場合があります。使用時点の最新の値をコピーして適用してください。

リクエスト URL の形式​

https://v.jp.kollus.com/s?jwt={JWT}&custom_key={CUSTOM_KEY}
注意
  • 標準 Claim の使用制限: RFC 7519 - Registered Claim Names規格の Claim を使用するとエラーが発生する場合があります。
  • ウォーターマーキングの有効化: ウォーターマーキング(Watermarking)機能はデフォルトで無効になっています。この機能を有効化するには、営業担当者(jp_sales@catenoid.net)までお問い合わせください。
  • iOS フルスクリーンモード: iOS 環境でフルスクリーンに切り替えると iOS Native プレイヤーが起動します。
  • 機能制限環境: iOS または Samsung インターネットブラウザでフルスクリーン再生時、ウォーターマーク表示など Kollus プレイヤー機能の動作が制限される場合があります。

JWT Payload 詳細規格​

必須オプションの適用例​

ユーザー（catenoid）が特定のコンテンツ（vnCVPVyV）を再生するための基本 Payload 構造です。

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

基本オプション​

オプションタイプ必須デフォルト値説明
cuidstring◯-ユーザー ID
  • 重複再生遮断・ブックマーク・続きから再生(nscreen)設定の基準値です。
  • 英数字の使用を推奨します。日本語や特殊文字を使用すると遮断履歴の検索が制限される場合があります。
exptinteger◯-JWT 有効期限 (Unix タイムスタンプ)
  • 最大値: 1893455999 (2029-12-31)
  • 有効期限後もサーバー時刻の誤差を考慮して最大 1 分までコンテンツへのアクセスが許可される場合があります。
mcarray◯-再生するコンテンツ情報を含む配列
next_episodeboolean-false次の動画 Callback 呼び出しの有無
  • true設定時、チャンネルに指定された次の動画 Callback が呼び出されます。
  • 最後のエピソードの場合、この値をfalseに設定して機能を無効化します。
playback_ratesarray--ユーザーが選択可能な再生速度リスト
  • 制限事項: PC プレイヤー専用オプション、モバイル App Player には適用不可
  • 形式: [再生速度リスト(array)、表示行数(rows)]
  • 例: [[0.5, 0.7, 1, 1.3, 1.5, 1.7, 2], 2]
    (説明: 7 つの再生速度オプションを UI 上で 2 行に分けて表示)
playcallback_ignoreboolean-falsePlay Callback の送信を無視するかどうか
  • true設定時、Play Callback をサーバーに送信しません。

コンテンツオプション (mc 配列内の設定)​

参考文書

キー(Key/ID)情報については、以下のドキュメントを参照してください。

オプションタイプ必須デフォルト値説明
mckeystring◯-メディアコンテンツキー
mcpfstring-nullエンコーディングプロファイルキー
  • 未入力の場合、再生環境に最適化されたプロファイルが自動選択されます。
titlestring-nullコンテンツタイトル
  • 未入力の場合、原本ファイルのタイトルが表示されます。
intrboolean-falseイントロ/アウトロ動画かどうか
  • true設定時、続きから再生・ LMS Callback など一部の機能が制限されます。
  • DRM ダウンロード時、本編ファイルのみダウンロードされます。
seekboolean-true再生位置の移動（シーク）が可能かどうか
  • false設定時、ブックマーク機能が無効化されます。
seekable_endinteger--1シーク許可の終了時点 (秒)
  • -1（デフォルト値）: シーク不可
  • seekオプションがfalseの場合でも、seekable_endが 10 であれば 0〜10 秒の区間内ではシークが許可されます。
disable_playrateboolean-false再生速度選択機能の無効化
  • true設定時、再生速度選択機能が無効化されます。
disable_nscreenboolean-false続きから再生機能の無効化
  • true設定時、続きから再生機能が無効化されます。
scroll_eventboolean-falseスクロールイベントの適用有無
  • true: 縦の長さ基準で動画エリアを調整
  • false: 横の長さ基準で動画エリアを調整
bookmarkboolean-trueブックマークボタンの表示有無

コンテンツ公開区間の設定​

Kollus VOD は原本ファイルの物理的な編集（カット、結合など）機能を提供しませんが、登録されたコンテンツの特定の区間のみをユーザーに公開するよう設定できます。

  • 機能定義: 原本動画内で視聴可能な開始時点（start_time）と終了時点（end_time）を指定して配信する機能です。
  • 主な特徴
    • 動画編集不可: アップロード済みの原本動画ファイル自体をカットや結合するなど、データレベルの物理的な編集はサポートしていません。
    • 特定区間の配信が可能: 設定された区間外の動画はユーザーのプレイヤーに読み込まれず、指定された特定の部分のみがユーザーに公開されます。
    • 柔軟な管理: 原本ファイルを複製したり再アップロードしたりする必要なく、設定値の変更だけで 1 つのファイルを複数の投稿として活用できます。
オプションタイプデフォルト値説明
play_section.start_timeintegernull再生区間の開始時点 (秒)
play_section.end_timeintegernull再生区間の終了時点 (秒)

字幕設定​

実装ガイド

特定の字幕のみを表示するには、filterとshow_by_filterオプションをどちらもtrueに設定してください。

オプションタイプデフォルト値説明
subtitle_policy.filter.namestringnull字幕フィルター - 字幕名
subtitle_policy.filter.language_codestringnull字幕フィルター - 言語コード
subtitle_policy.filter_main.namestringnullメイン字幕フィルター - 字幕名
subtitle_policy.filter_main.language_codestringnullメイン字幕フィルター - 言語コード
subtitle_policy.filter_sub.namestringnullサブ字幕フィルター - 字幕名
subtitle_policy.filter_sub.language_codestringnullサブ字幕フィルター - 言語コード
subtitle_policy.show_by_filterbooleanfalseフィルター基準に基づく字幕の表示有無
subtitle_policy.is_showablebooleanfalse字幕の表示有無

ウォーターマーキング​

画面にユーザー識別情報をオーバーレイして、不正録画および情報漏洩を防止します。

参考
  • 機能の有効化: ウォーターマーキング機能はデフォルトで無効になっています。この機能を有効化するには、営業担当者(jp_sales@catenoid.net)までお問い合わせください。
  • 改ざん防止: 外部スクリプト(JavaScript Injection)によるウォーターマークの改ざん防止機能がデフォルトで適用されます。
オプションタイプデフォルト値説明
video_watermarking_code_policy.code_kindstring-ウォーターマーク表示テキスト
  • "client_user_id"を入力するとcuidが表示され、一般の文字列を入力するとそのテキストがそのまま表示されます。
video_watermarking_code_policy.font_sizeinteger7ウォーターマークテキストサイズ (px)
video_watermarking_code_policy.font_colorstring"FFFFFF"ウォーターマークの色 (hex)
video_watermarking_code_policy.alphainteger200ウォーターマークの透明度 (0〜255)
video_watermarking_code_policy.show_timeinteger1ウォーターマーク表示持続時間 (秒)
video_watermarking_code_policy.hide_timeinteger60ウォーターマーク非表示持続時間 (秒)
video_watermarking_code_policy.show_pausedbooleanfalse一時停止中のウォーターマーク表示有無
video_watermarking_code_policy.enable_html5_playerbooleanfalseKollus Web Player の使用有無
  • true: Kollus Web Player で再生されます。
  • false: App Player for Windows で再生されます。
PHP 実装例
<?php
/**
* base64_urlencode
*
* @param string $str
* @return string
*/
function base64_urlencode($str) {
    return rtrim(strtr(base64_encode($str), '+/', '-_'), '=');
}

/**
* jwt_encode
*
* @param array $payload
* @param string $key
* @return string
*/
function jwt_encode($payload, $key) {
    $jwtHead = base64_urlencode(json_encode(array('typ' => 'JWT', 'alg' => 'HS256')));
    $jsonPayload = base64_urlencode(json_encode($payload));
    $signature = base64_urlencode(hash_hmac('SHA256', $jwtHead . '.' . $jsonPayload, $key, true));

    return $jwtHead . '.' . $jsonPayload . '.' . $signature;
}

$securityKey = 'SECURITY_KEY';
$customKey = 'CUSTOM_KEY';
$mediaContentKey = 'MEDIA_CONTENT_KEY';
$clientUserId = 'CLIENT_USER_ID';
$expireTime =  7200; // 120 minutes
$mediaItems = array(
  array(
        'media_content_key' => $mediaContentKey,
    ),
);

$payload = array(
    'mc' => array(),
    'cuid' => $clientUserId,
    'expt' => time() + $expireTime,
  'video_watermarking_code_policy' =>
      array(
        'code_kind' => '2930451',
        'font_size' => 20,
        'font_color' => 'ffffff',
        'show_time' => 10,
        'hide_time' => 1,
        'alpha' => 255,
        'enable_html5_player' => true
      ),
);

foreach ($mediaItems as $mediaItem) {
    $mcClaim = array();
    $mcClaim['mckey'] = $mediaItem['media_content_key'];
    $payload['mc'][] = $mcClaim;
}

$jwtToken = jwt_encode($payload, $securityKey);

$webTokenURL = 'https://v.jp.kollus.com/s?jwt=' . $jwtToken . '&custom_key=' . $customKey;
?>

<!DOCTYPE html>
<html lang="en">
<body>
    <iframe width="840" height="472" src="<?php echo $webTokenURL; ?>" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>
</body>
</html>

使用例​

イントロ + 本編 + アウトロの連続再生​

イントロ・本編・アウトロを 1 つの途切れないコンテンツとして再生するよう構成した例です。

{
  "cuid": "{END_USER_ID}",
  "expt": 1735660800,
  "mc": [
    {
      "mckey": "gDV2B1ZG",
      "intr": true
    },
    {
      "mckey": "vnCVPVyV"
    },
    {
      "mckey": "eBzkZtzG",
      "intr": true
    }
  ]
}

イントロ動画後に本編を連続再生​

イントロのシーク(Seek)を禁止し、本編へ自動移行するよう構成した例です。

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

0〜30 秒の区間のみシーク(Seek)を許可​

全体シークをブロックし、冒頭 30 秒のみシーク可能に設定してプレビュー動画として活用する例です。

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

視聴済み区間のみシークを許可​

視聴済み区間内のシークのみ許可し、未視聴区間への任意のシークを制限する例です。

{
  "cuid": "{END_USER_ID}",
  "expt": 1735660800,
  "mc": [
    {
      "mckey": "vnCVPVyV",
      "seekable_end": 1,
      "seek": false
    }
  ]
}

ウォーターマーキングの適用​

ユーザー ID（cuid）を画面に 3 秒間表示し、300 秒（5 分）間非表示にするセキュリティポリシーの適用例です。

{
  "cuid": "{END_USER_ID}",
  "expt": 1735660800,
  "video_watermarking_code_policy": {
    "code_kind": "client_user_id",
    "font_size": 10,
    "font_color": "FFFFFF",
    "alpha": 128,
    "show_time": 3,
    "hide_time": 300
  },
  "mc": [
    {
      "mckey": "vnCVPVyV"
    }
  ]
}
サンプルコードリポジトリのリンク

全サンプルコード(PHP)はKollus GitHub リポジトリで確認できます。