DRM Download Callback

お知らせ

このドキュメントは機械翻訳で作成された下書きであり、現在レビュー中です。機械翻訳の特性上、一部の内容が不正確であったり、韓国語の原文と異なる場合があります。より正確な情報については、韓国語のドキュメントをご参照ください。

Kollus VOD は、ユーザーがコンテンツをデバイスにダウンロードしたり、保存されたファイルをオフライン状態で再生する際にセキュリティ権限を検証する DRM Download Callback 機能をサポートしています。これにより、ダウンロードの許可可否、再生可能回数、有効期限などの精緻な DRM ポリシーをリアルタイムで制御できます。

注意事項

データ整合性: レスポンスデータのタイプが一致しない場合や範囲外の場合、ダウンロードおよび再生が即座にブロックされます。
設定の取り消し不可: 誤って送信された有効期限日時(expiration_date)などの設定値は Kollus システム内で任意に修正またはキャンセルできないため、正確な値を送信する必要があります。
サーバーの可用性: Callback サーバーのレスポンス遅延や障害発生時にサービス利用が制限されるため、安定したサーバー環境の構成を推奨します。

Callback の設定方法

Callback URL は Kollus VOD コンソールで設定できます。

参考文書: Callback 連携 - DRM Download Callback

Callback フロー

注意

レスポンス仕様: Callback サーバーのレスポンスデータは必ず**JWT(JSON Web Token)**形式で返却される必要があります。
ヘッダー認証: HTTP レスポンスヘッダーにX-KOLLUS-USERKEY: {CUSTOM_KEY}を必ず含める必要があります。
- 確認方法: Kollus VOD コンソール > [サービスアカウント] > [カスタムキー]
データタイプ: JSON 内のすべての整数型フィールド(expiration_date、result、content_expiredなど)はinteger型で渡す必要があります。("1"のように string 型で送信すると処理に失敗します)

Callback の種類

DRM Download Callback は処理目的に応じて 3 種類に分類されます。

kind1（ダウンロード承認）: ユーザーがダウンロードボタンをクリックした際にサーバーで権限および DRM ポリシーを割り当てます。
kind2（ダウンロード完了通知）: デバイスへのファイル保存が 100%完了した時点で結果データを送信します。
kind3（オフライン再生権限確認）: 保存されたコンテンツを再生するたびに再生権限および有効期限の確認を行います。

リクエスト仕様

送信方式

Method: POST
Content-Type: application/x-www-form-urlencoded
Data Format: itemsパラメーターにJSONArray形式の JSON 文字列を含めて送信

kind1、kind2 リクエストパラメーター

items

パラメーター	タイプ	必須	説明
`kind`	`integer`	◯	DRM Download Callback の種類 `1`: ダウンロード承認 `2`: ダウンロード完了通知
`client_user_id`	`string`	◯	ユーザー ID（JWT 生成時に入力した`client_user_id`）
`player_id`	`string`	◯	Kollus Player 固有 ID
`hardware_id`	`string`	-	ハードウェア ID（Windows 環境など識別可能な値が存在する場合に提供）
`device_name`	`string`	-	デバイスのモデル名
`media_content_key`	`string`	◯	メディアコンテンツキー
`localtime`	`integer`	-	リクエスト時点のデバイス時刻(Unix timestamp)
`uservalues`	`JSON string`	-	カスタム変数（`uservalue0`〜`uservalue99`）

kind1、kind2 items の例

[
  {
    "kind": 1,
    "media_content_key" : "{MEDIA_CONTENT_KEY}",
    "client_user_id": "{END_USER_ID}",
    "player_id": "{PLAYER_ID}",
    "device_name": "{DEVICE_NAME}",
    "uservalues": {
      "uservalue0": "value0"
    }
  }
]

kind3 リクエストパラメーター

items

パラメーター	タイプ	必須	説明
`kind`	`integer`	◯	DRM Download Callback の種類 `3`: オフライン再生権限確認
`session_key`	`string`	◯	有効期限更新(Renewal)のためのセッションキー（`content_expire_reset`リクエスト時の整合性検証に使用）
`client_user_id`	`string`	◯	ユーザー ID（JWT 生成時に入力した`client_user_id`）
`player_id`	`string`	◯	Kollus Player 固有 ID
`hardware_id`	`string`	-	ハードウェア ID（Windows 環境など識別可能な値が存在する場合に提供）
`device_name`	`string`	-	デバイスのモデル名
`media_content_key`	`string`	◯	メディアコンテンツキー
`start_at`	`integer`	◯	送信リクエスト時点のローカル時刻
`uservalues`	`JSON string`	-	カスタム変数（`uservalue0`〜`uservalue99`）
`content_expired`	`integer`	-	再生有効期限状態 `0`: 再生可能 `1`: 再生ブロック（有効期限切れ）
`check_expired`	`integer`	-	検証有効期間の期限切れ状態 `0`: 正常 `1`: 期限切れ
`reset_req`	`integer`	-	一括更新リクエスト状態 `0`（デフォルト値）: 通常更新 `1`: 一括更新
`expiration_date`	`integer`	-	再生有効期限日時(Unix timestamp)
`localtime`	`integer`	-	リクエスト時点のデバイス時刻(Unix timestamp)

kind3 items の例

[
  {
    "kind": 3,
    "session_key" : "{SESSION_KEY}",
    "media_content_key" : "{MEDIA_CONTENT_KEY}",
    "client_user_id": "{END_USER_ID}",
    "player_id": "{PLAYER_ID}",
    "device_name": "{DEVICE_NAME}",
    "uservalues": {
      "uservalue1": "value1"
    }
  }
]

uservalues の例

{
  "uservalue0": "class_code_01",
  "uservalue1": "product_code_02",
  "uservalue99": "custom_code_03"
}

レスポンス仕様

送信方式

DRM Download Callback のレスポンスは、データのセキュリティと整合性のために必ず JWT(JSON Web Token)形式にエンコードして返却する必要があります。

Header: X-KOLLUS-USERKEY: {CUSTOM_KEY}
Content-Type: text/plain

Payload 構造: dataフィールド内に個別コンテンツのレスポンスオブジェクトを含む配列構造

{
  "data": [
    { "kind": 1, "media_content_key": "...", "result": 1, ... },
    { "kind": 1, "media_content_key": "...", "result": 1, ... }
  ]
}

DRM 有効期限オプション仕様

注意

有効期限オプションは Kollus システムに記録された後、修正または取り消しができません。必ず正確な Unix timestamp 値を設定してください。

オプション	タイプ	許容範囲	説明
`expiration_count`	`integer`	0（制限なし）〜 1000	再生許可回数
`expiration_date`	`integer`	0（制限なし）〜 2145916799(2037-12-31 23:59:59)	再生有効期限日時(Unix timestamp)
`expiration_playtime`	`integer`	0（制限なし）、60（60 秒）〜 604800（7 日）	再生制限時間(sec)

kind1 レスポンスフィールド

ユーザーのダウンロードリクエストに対してサーバーが承認可否を決定し、該当デバイスに保存されるコンテンツの DRM ポリシーを割り当てます。

data の項目

フィールド	タイプ	必須	デフォルト値	説明
`kind`	`integer`	◯	-	DRM Download Callback の種類 `1`: ダウンロード承認
`media_content_key`	`string`	◯	-	メディアコンテンツキー
`expiration_date`	`integer`	-	-	再生有効期限日時(Unix timestamp)
`expiration_count`	`integer`	-	-	再生許可回数（例: `10` → 10 回再生可能）
`expiration_playtime`	`integer`	-	-	再生制限時間（例: `60` → 60 秒、`3600` → 1 時間再生可能）
`expiration_playtime_type`	`integer`	-	-	再生時間の差し引き方式 `1`: 実際の再生時間基準で差し引き
`result`	`integer`	◯	-	承認結果 `0`: 失敗/ブロック `1`: 成功/許可
`message`	`string`	-	-	再生ブロック(`result: 0`)時にプレイヤー画面に表示する案内メッセージ（未入力時は Kollus デフォルトエラーメッセージを表示）
`expiration_refresh_popup`	`integer`	-	`0`	有効期限切れ時の更新(Renewal)通知の表示可否 `0`: 非表示 `1`: 表示
`vmcheck`	`integer`	-	`1`	（HTML5 Player for PC 専用）仮想マシン(VM)環境での再生許可可否 `0`: 許可 `1`（デフォルト値）: 仮想マシン環境の検知およびブロック
`check_abuse`	`integer`	-	`0`	オフライン再生時の`kind3`呼び出し可否 `0`: 呼び出さない `1`: 常に呼び出す
`offline_bookmark.download`	`integer`	-	`0`	ブックマークデータの同時ダウンロード可否 `0`: ダウンロードしない `1`: ダウンロードする
`offline_bookmark.readonly`	`integer`	-	`0`	オフライン状態でのブックマーク編集権限 `0`: 編集可能 `1`: 読み取り専用

kind1 レスポンス例

{
  "data" : [
    {
      "kind": 1,
      "media_content_key": "{MEDIA_CONTENT_KEY}",
      "expiration_date": 1402444800,
      "expiration_playtime": 1800,
      "result": 1
    }
  ]
}

kind2 レスポンスフィールド

コンテンツのダウンロードプロセスが正常に完了したことをサーバーに通知し、サーバーはレスポンスを通じて該当コンテンツの有効性を最終確定します。

data の項目

フィールド	タイプ	必須	デフォルト値	説明
`kind`	`integer`	◯	-	DRM Download Callback の種類 `2`: ダウンロード完了通知
`media_content_key`	`string`	◯	-	メディアコンテンツキー
`content_delete`	`integer`	-	`0`	ダウンロード完了直後のファイル削除可否 `0`: 削除しない `1`: 削除する
`message`	`string`	-	-	再生ブロック（`result: 0`または`content_expired: 1`）時にプレイヤーに表示する案内メッセージ（未入力時は Kollus デフォルトエラーメッセージを表示）
`check_expiration_date`	`integer`	-	`0`	検証有効期間(Unix timestamp) `0`入力時は制限なしとして処理
`result`	`integer`	◯	-	処理結果 `0`: 異常（オプション無視） `1`: 正常

kind2 レスポンス例

{
  "data" : [
    {
      "kind": 2,
      "media_content_key": "{MEDIA_CONTENT_KEY}",
      "content_delete": 1,
      "result": 1
    }
  ]
}

kind3 レスポンスフィールド

data の項目

フィールド	タイプ	必須	デフォルト値	説明
`kind`	`integer`	◯	-	DRM Download Callback の種類 `3`: オフライン再生権限確認
`session_key`	`string`	-	-	有効期限日時更新(Renewal)のためのセッションキー（`content_expire_reset`リクエスト時の整合性検証に使用）
`media_content_key`	`string`	◯	-	メディアコンテンツキー
`start_at`	`integer`	◯	-	リクエスト時に受信した`start_at`値をそのまま返却
`content_expired`	`integer`	-	`0`	コンテンツ強制有効期限処理 `0`: 再生可能 `1`: 再生ブロック
`content_delete`	`integer`	-	`0`	ダウンロード完了直後のファイル削除可否 `0`: 削除しない `1`: 削除する
`content_expire_reset`	`integer`	-	`0`	既存の有効期限ポリシーの初期化 `0`: 初期化しない `1`: 初期化する
`expiration_date`	`integer`	-	-	再生有効期限日時(Unix timestamp)
`expiration_count`	`integer`	-	-	再生許可回数（例: `10` → 10 回再生可能）
`expiration_playtime`	`integer`	-	-	再生制限時間（例: `60` → 60 秒、`3600` → 1 時間再生可能）
`result`	`integer`	◯	-	処理結果 `0`: 異常（オプション無視） `1`: 正常
`message`	`string`	-	-	再生ブロック（`result: 0`または`content_delete: 1`または`content_expired: 1`）時にプレイヤーに表示する案内メッセージ（未入力時は Kollus デフォルトエラーメッセージを表示）
`check_abuse`	`integer`	-	`0`	オフライン再生時の`kind3`呼び出し可否 `0`: 呼び出さない `1`: 常に呼び出す
`check_expiration_date`	`integer`	-	`0`	検証有効期間(Unix timestamp) `0`: 制限なし

初期化オプション

初期化可能なオプション（content_expire_reset: 1を設定した場合）
- expiration_date（再生有効期限日時）
- expiration_count（再生許可回数）
- expiration_playtime（再生制限時間）
- check_expiration_date（検証有効期間）
初期化が無視される条件: content_expiredの値が1の場合、content_expire_resetを1に設定しても初期化ロジックは無視され、再生がブロックされます。

kind3 レスポンス例

{
  "data": [
    {
      "kind": 3,
      "session_key": "{SESSION_KEY}",
      "media_content_key": "{MEDIA_CONTENT_KEY}",
      "start_at": 140000000,
      "result": 1,
      "content_expired": 1,
      "content_delete": 1,
      "content_expire_reset": 1,
      "expiration_date": 1402444800,
      "expiration_count": 10,
      "expiration_playtime": 3600
    }
  ]
}

デバイス識別情報(device_name)の詳細

device_nameはプレイヤー呼び出し時にデバイスを識別するために渡される情報です。オペレーティングシステム環境に応じて以下の仕様で送信されます。

Android

Android アプリでは、デバイスのBuild.DEVICEとBuild.MODELを/（スラッシュ）で組み合わせた文字列を使用します。

仕様: Build.DEVICE/Build.MODEL
例: samsung/SM-G991N、google/Pixel_6

iOS

iOS アプリでは、Apple が提供するdevice_nameをそのまま使用します。

iOS device_name 全一覧

デバイス	device_name
iPhone1,1	iPhone
iPhone1,2	iPhone 3G
iPhone2,1	iPhone 3GS
iPhone3,1	iPhone 4 (GSM)
iPhone3,3	iPhone 4 CDMA
iPhone4,1	iPhone 4S
iPhone5,1	iPhone 5 A1428
iPhone5,2	iPhone 5 A1429
iPhone5,3	iPhone 5c A1456/A1532
iPhone5,4	iPhone 5c A1507/A1516/A1529
iPhone6,1	iPhone 5s A1433/A1453
iPhone6,2	iPhone 5s A1457/A1518/A1530
iPhone7,1	iPhone 6 Plus
iPhone7,2	iPhone 6
iPhone8,1	iPhone 6s
iPhone8,2	iPhone 6s Plus
iPhone8,4	iPhone SE
iPhone9,1	iPhone 7 A1660/A1779/A1780
iPhone9,2	iPhone 7 Plus A1661/A1785/A1786
iPhone9,3	iPhone 7 A1778
iPhone9,4	iPhone 7 Plus A1784
iPhone10,1	iPhone 8 A1863/A1906
iPhone10,2	iPhone 8 Plus A1864/A1898
iPhone10,3	iPhone X A1865/A1902
iPhone10,4	iPhone 8 A1905
iPhone10,5	iPhone 8 Plus A1897
iPhone10,6	iPhone X A1901
iPhone11,2	iPhone XS
iPhone11,4	iPhone XS Max
iPhone11,6	iPhone XS Max
iPhone11,8	iPhone XR
iPhone12,1	iPhone 11
iPhone12,3	iPhone 11 Pro
iPhone12,5	iPhone 11 Pro Max
iPhone12,8	iPhone SE (2nd gen)
iPhone13,1	iPhone 12 mini
iPhone13,2	iPhone 12
iPhone13,3	iPhone 12 Pro
iPhone13,4	iPhone 12 Pro Max
iPhone14,2	iPhone 13 Pro
iPhone14,3	iPhone 13 Pro Max
iPhone14,4	iPhone 13 mini
iPhone14,5	iPhone 13
iPhone14,6	iPhone SE (3rd gen)
iPhone14,7	iPhone 14
iPhone14,8	iPhone 14 Plus
iPhone15,2	iPhone 14 Pro
iPhone15,3	iPhone 14 Pro Max
iPhone15,4	iPhone 15
iPhone15,5	iPhone 15 Plus
iPhone16,1	iPhone 15 Pro
iPhone16,2	iPhone 15 Pro Max
iPhone17,1	iPhone 16 Pro
iPhone17,2	iPhone 16 Pro Max
iPhone17,3	iPhone 16
iPhone17,4	iPhone 16 Plus
iPhone17,5	iPhone 16e
iPad1,1	iPad
iPad2,1	iPad 2 WiFi
iPad2,2	iPad 2 (GSM)
iPad2,3	iPad 2 CDMA
iPad2,4	iPad 2 WiFi (revised)
iPad2,5	iPad mini WiFi
iPad2,6	iPad mini A1454
iPad2,7	iPad mini A1455
iPad3,1	iPad 3rd gen (WiFi)
iPad3,2	iPad 3rd gen (WiFi+LTE Verizon)
iPad3,3	iPad 3rd gen (WiFi+LTE AT&T)
iPad3,4	iPad 4th gen (WiFi)
iPad3,5	iPad 4th gen A1459
iPad3,6	iPad 4th gen A1460
iPad4,1	iPad Air WiFi
iPad4,2	iPad Air WiFi+LTE
iPad4,3	iPad Air Rev
iPad4,4	iPad mini 2 WiFi
iPad4,5	iPad mini 2 WiFi+LTE
iPad4,6	iPad mini 2 Rev
iPad4,7	iPad mini 3 WiFi
iPad4,8	iPad mini 3 A1600
iPad4,9	iPad mini 3 A1601
iPad5,1	iPad mini 4 WiFi
iPad5,2	iPad mini 4 WiFi+LTE
iPad5,3	iPad Air 2 WiFi
iPad5,4	iPad Air 2 WiFi+LTE
iPad6,3	iPad Pro 9.7 inch WiFi
iPad6,4	iPad Pro 9.7 inch WiFi+LTE
iPad6,7	iPad Pro 12.9 inch WiFi
iPad6,8	iPad Pro 12.9 inch WiFi+LTE
iPad6,11	iPad 9.7 Inch 5th Gen WiFi Only
iPad6,12	iPad 9.7 Inch 5th Gen WiFi/Cellular
iPad7,1	iPad Pro 12.9 inch A1670
iPad7,2	iPad Pro 12.9 inch A18219
iPad7,3	iPad Pro 10.5 inch A1701
iPad7,4	iPad Pro 10.5 inch A1709
iPad7,5	iPad 6th gen A1893
iPad7,6	iPad 6th gen A1954
iPad7,11	iPad 7th gen (WiFi)
iPad7,12	iPad 7th gen (WiFi+Cellular)
iPad8,1	iPad Pro 11 inch 1st gen (WiFi)
iPad8,2	iPad Pro 11 inch 1st gen (WiFi+LTE 256GB)
iPad8,3	iPad Pro 11 inch 1st gen (WiFi+LTE 512GB)
iPad8,4	iPad Pro 11 inch 1st gen (WiFi+LTE 1TB)
iPad8,5	iPad Pro 12.9 inch 3rd gen (WiFi)
iPad8,6	iPad Pro 12.9 inch 3rd gen (WiFi+LTE 256GB)
iPad8,7	iPad Pro 12.9 inch 3rd gen (WiFi+LTE 512GB)
iPad8,8	iPad Pro 12.9 inch 3rd gen (WiFi+LTE 1TB)
iPad8,9	iPad Pro 11 inch 2nd gen (WiFi)
iPad8,10	iPad Pro 11 inch 2nd gen (WiFi+LTE)
iPad8,11	iPad Pro 12.9 inch 4th gen (WiFi)
iPad8,12	iPad Pro 12.9 inch 4th gen (WiFi+LTE)
iPad11,1	iPad mini 5th gen (WiFi)
iPad11,2	iPad mini 5th gen (WiFi+LTE)
iPad11,3	iPad Air 3rd gen (WiFi)
iPad11,4	iPad Air 3rd gen (WiFi+LTE)
iPad11,6	iPad 8th gen (WiFi)
iPad11,7	iPad 8th gen (WiFi+LTE)
iPad12,1	iPad 9th gen (WiFi)
iPad12,2	iPad 9th gen (WiFi+LTE)
iPad13,1	iPad Air 4th gen (WiFi)
iPad13,2	iPad Air 4th gen (WiFi+LTE)
iPad13,4	iPad Pro 11 inch 3rd gen (WiFi)
iPad13,5	iPad Pro 11 inch 3rd gen (WiFi+LTE 512GB)
iPad13,6	iPad Pro 11 inch 3rd gen (WiFi+LTE 2TB)
iPad13,7	iPad Pro 11 inch 3rd gen (WiFi 2TB)
iPad13,8	iPad Pro 12.9 inch 5th gen (WiFi)
iPad13,9	iPad Pro 12.9 inch 5th gen (WiFi+LTE 512GB)
iPad13,10	iPad Pro 12.9 inch 5th gen (WiFi+LTE 2TB)
iPad13,11	iPad Pro 12.9 inch 5th gen (WiFi 2TB)
iPad13,16	iPad Air 5th gen (WiFi)
iPad13,17	iPad Air 5th gen (WiFi+LTE)
iPad13,18	iPad 10th gen (WiFi)
iPad13,19	iPad 10th gen (WiFi+LTE)
iPad14,1	iPad mini 6th gen (WiFi)
iPad14,2	iPad mini 6th gen (WiFi+LTE)
iPad14,3	iPad Pro 11 inch 4th gen (WiFi)
iPad14,4	iPad Pro 11 inch 4th gen (WiFi+LTE)
iPad14,5	iPad Pro 12.9 inch 6th gen (WiFi)
iPad14,6	iPad Pro 12.9 inch 6th gen (WiFi+LTE)
iPad14,8	iPad Air 11 inch M2 (WiFi)
iPad14,9	iPad Air 11 inch M2 (WiFi+LTE)
iPad14,10	iPad Air 13 inch M2 (WiFi)
iPad14,11	iPad Air 13 inch M2 (WiFi+LTE)
iPad16,1	iPad mini 7th gen (WiFi)
iPad16,2	iPad mini 7th gen (WiFi+LTE)
iPad16,3	iPad Pro 11 inch M4 (WiFi)
iPad16,4	iPad Pro 11 inch M4 (WiFi+LTE)
iPad16,5	iPad Pro 13 inch M4 (WiFi)
iPad16,6	iPad Pro 13 inch M4 (WiFi+LTE)
iPad16,7	iPad 11th gen (WiFi)
iPad16,8	iPad 11th gen (WiFi+LTE)
iPod1,1	iPod touch
iPod2,1	iPod touch 2nd gen
iPod3,1	iPod touch 3rd gen
iPod4,1	iPod touch 4th gen
iPod5,1	iPod touch 5th gen
iPod7,1	iPod touch 6th gen
iPod9,1	iPod touch 7th gen

注意事項​

Callback の設定方法​

Callback フロー​

Callback の種類​

リクエスト仕様​

送信方式​

kind1、kind2 リクエストパラメーター​

items​

kind1、kind2 items の例​

kind3 リクエストパラメーター​

items​

kind3 items の例​

uservalues の例​

レスポンス仕様​

送信方式​

DRM 有効期限オプション仕様​

kind1 レスポンスフィールド​

data の項目​

kind1 レスポンス例​

kind2 レスポンスフィールド​

data の項目​

kind2 レスポンス例​

kind3 レスポンスフィールド​

data の項目​

kind3 レスポンス例​

デバイス識別情報(device_name)の詳細​

Android​

iOS​

注意事項

Callback の設定方法

Callback フロー

Callback の種類

リクエスト仕様

送信方式

kind1、kind2 リクエストパラメーター

items

kind1、kind2 items の例

kind3 リクエストパラメーター

items

kind3 items の例

uservalues の例

レスポンス仕様

送信方式

DRM 有効期限オプション仕様

kind1 レスポンスフィールド

data の項目

kind1 レスポンス例

kind2 レスポンスフィールド

data の項目

kind2 レスポンス例

kind3 レスポンスフィールド

data の項目

kind3 レスポンス例

デバイス識別情報(device_name)の詳細

Android

iOS