Skip to main content

DRM Download Callback

Notice

This document is a machine-translated draft and is currently undergoing review. Some content may be inaccurate or differ from the original Korean version. For the most precise information, refer to the Korean documentation.

Kollus VOD supports the DRM download callback feature, which verifies security permissions when a user downloads content to a device or plays a stored file in an offline state. This allows you to control sophisticated DRM policies in real time, such as whether downloads are permitted, the number of allowed playbacks, and the expiration period.

Notes​

  • Data integrity: If the type of response data does not match or is out of range, downloads and playback will be immediately blocked.
  • Settings cannot be revoked: Setting values such as incorrectly transmitted expiration date and time (expiration_date) cannot be arbitrarily modified or canceled within the Kollus system, so accurate values must be transmitted.
  • Server availability: Service use may be restricted if there are callback server response delays or failures, so a stable server environment is recommended.

How to configure the callback​

The callback URL can be configured in the Kollus VOD console.

Callback flow​

Caution
  • Response specifications: The response data from the callback server must be returned in JWT(JSON Web Token) format.
  • Header authentication: X-KOLLUS-USERKEY: {CUSTOM_KEY} must be included in the HTTP response header.
    • Where to find: Kollus VOD console > [Settings] > [Custom key]
  • Data types: All integer fields in JSON (expiration_date, result, content_expired, etc.) must be passed as integer type. (Sending as string type such as "1" will result in processing failure)

Callback types​

DRM download callbacks are divided into three types according to their processing purpose.

  • kind 1 (Download approval): When a user clicks the download button, the server assigns permissions and DRM policies.
  • kind 2 (Download completion notification): Sends result data when file saving to the device is 100% complete.
  • kind 3 (Offline playback permission check): Checks playback permissions and expiration status every time stored content is played.

Request specifications​

delivery method​

  • Method: POST
  • Content-Type: application/x-www-form-urlencoded
  • Data Format: Transmitted with a JSON string in JSONArray format included in the items parameter

kind 1, kind 2 request parameters​

Items​

ParameterTypeRequiredDescription
kindinteger◯DRM download callback type
  • 1: Download approval
  • 2: Download completion notification
client_user_idstring◯User ID (the client_user_id entered when generating the JWT)
player_idstring◯Kollus Player unique ID
hardware_idstring-Hardware ID (provided when an identifiable value exists, such as in a Windows environment)
device_namestring-Device model name
media_content_keystring◯Media content key
localtimeinteger-Device time at the time of the request (Unix timestamp)
uservaluesJSON string-Custom variables (uservalue0–uservalue99)

kind 1, kind 2 items example​

[
  {
    "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"
    }
  }
]

kind 3 request parameters​

Items​

ParameterTypeRequiredDescription
kindinteger◯DRM download callback type
  • 3: Offline playback permission check
session_keystring◯Session key for expiration date renewal (used for consistency verification when requesting content_expire_reset)
client_user_idstring◯User ID (the client_user_id entered when generating the JWT)
player_idstring◯Kollus Player unique ID
hardware_idstring-Hardware ID (provided when an identifiable value exists, such as in a Windows environment)
device_namestring-Device model name
media_content_keystring◯Media content key
start_atinteger◯Local time at the time of the transfer request
uservaluesJSON string-Custom variables (uservalue0–uservalue99)
content_expiredinteger-Playback expiration status
  • 0: Playback available
  • 1: Playback blocked (expired)
check_expiredinteger-Verification validity period expiration status
  • 0: Normal
  • 1: Expired
reset_reqinteger-Batch update request status
  • 0: Normal update (default)
  • 1: Batch update
expiration_dateinteger-Playback expiration date and time (Unix timestamp)
localtimeinteger-Device time at the time of the request (Unix timestamp)

kind 3 items example​

[
  {
    "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 example​

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

Response specifications​

delivery method​

DRM download callback responses must be encoded and returned in JWT(JSON Web Token) format for data security and integrity.

  • Header: X-KOLLUS-USERKEY: {CUSTOM_KEY}
  • Content-Type: text/plain
  • Payload structure: Array structure containing individual content response objects within the data field 
    {
      "data": [
        { "kind": 1, "media_content_key": "...", "result": 1, ... },
        { "kind": 1, "media_content_key": "...", "result": 1, ... }
      ]
    }

DRM expiration option specifications​

Caution

Expiration options cannot be modified or revoked after being recorded in the Kollus system. Be sure to assign accurate Unix timestamp values.

OptionTypeAllowed rangeDescription
expiration_countinteger0 (no limit) – 1000Number of allowed playbacks
expiration_dateinteger0 (no limit) – 2145916799 (2037-12-31 23:59:59)Playback expiration date and time (Unix timestamp)
expiration_playtimeinteger0 (no limit), 60 (60 seconds) – 604800 (7 days)Playback time limit (sec)

kind 1 response fields​

The server determines whether to approve the user's download request and assigns the DRM policy for the content to be stored on the device.

Data items​

FieldTypeRequiredDefaultDescription
kindinteger◯-DRM download callback type
  • 1: Download approval
media_content_keystring◯-Media content key
expiration_dateinteger--Playback expiration date and time (Unix timestamp)
expiration_countinteger--Number of allowed playbacks (e.g., 10 → 10 playbacks allowed)
expiration_playtimeinteger--Playback time limit (e.g., 60 → 60 seconds, 3600 → 1 hour of playback available)
expiration_playtime_typeinteger--Playback time deduction method
  • 1: Deducted based on actual playback time
resultinteger◯-Approval result
  • 0: Failure/blocked
  • 1: Success/allowed
messagestring--Guidance message to display on the player screen when playback is blocked (result: 0) (Kollus default error message is displayed if not entered)
expiration_refresh_popupinteger-0Whether to show renewal notification upon expiration
  • 0: Not shown
  • 1: Shown
vmcheckinteger-1(HTML5 Player for PC only) Whether to allow playback in a virtual machine(VM) environment
  • 0: Allowed
  • 1: Detect and block virtual machine environment (default)
check_abuseinteger-0Whether to call kind 3 during offline playback
  • 0: Do not call
  • 1: Always call
offline_bookmark.downloadinteger-0Whether to simultaneously download bookmark data
  • 0: Do not download
  • 1: Download
offline_bookmark.readonlyinteger-0Bookmark editing permissions in offline state
  • 0: Editable
  • 1: Read-only

kind 1 response example​

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

kind 2 response fields​

Notifies the server that the content download process has completed successfully, and the server finalizes the validity of the content through the response.

Data items​

FieldTypeRequiredDefaultDescription
kindinteger◯-DRM download callback type
  • 2: Download completion notification
media_content_keystring◯-Media content key
content_deleteinteger-0Whether to delete the file immediately after download completes
  • 0: Do not delete
  • 1: Delete
messagestring--Guidance message to display on the player when playback is blocked (result: 0 or content_expired: 1) (Kollus default error message is displayed if not entered)
check_expiration_dateinteger-0Verification validity period (Unix timestamp)
  • When 0 is entered, treated as no limit
resultinteger◯-Processing result
  • 0: Abnormal (options ignored)
  • 1: Normal

kind 2 response example​

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

kind 3 response fields​

Data items​

FieldTypeRequiredDefaultDescription
kindinteger◯-DRM download callback type
  • 3: Offline playback permission check
session_keystring--Session key for expiration date renewal (used for consistency verification when requesting content_expire_reset)
media_content_keystring◯-Media content key
start_atinteger◯-Returns the start_at value received in the request as-is
content_expiredinteger-0Force content expiration processing
  • 0: Playback available
  • 1: Playback blocked
content_deleteinteger-0Whether to delete the file immediately after download completes
  • 0: Do not delete
  • 1: Delete
content_expire_resetinteger-0Reset existing expiration policy
  • 0: Do not reset
  • 1: Reset
expiration_dateinteger--Playback expiration date and time (Unix timestamp)
expiration_countinteger--Number of allowed playbacks (e.g., 10 → 10 playbacks allowed)
expiration_playtimeinteger--Playback time limit (e.g., 60 → 60 seconds, 3600 → 1 hour of playback available)
resultinteger◯-Processing result
  • 0: Abnormal (options ignored)
  • 1: Normal
messagestring--Guidance message to display on the player when playback is blocked (result: 0 or content_delete: 1 or content_expired: 1) (Kollus default error message is displayed if not entered)
check_abuseinteger-0Whether to call kind 3 during offline playback
  • 0: Do not call
  • 1: Always call
check_expiration_dateinteger-0Verification validity period (Unix timestamp)
  • 0: No limit
Reset options
  • Resettable options (when content_expire_reset: 1 is set)
    • expiration_date (playback expiration date and time)
    • expiration_count (number of allowed playbacks)
    • expiration_playtime (playback time limit)
    • check_expiration_date (verification validity period)
  • Reset ignored condition: If the content_expired value is 1, the reset logic is ignored and playback is blocked even if content_expire_reset is set to 1.

kind 3 response example​

{
  "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 identification information (device_name) details​

device_name is the information passed to identify the device when the player is called. It is transmitted in the following specifications depending on the operating system environment.

Android​

In Android apps, a string combining the device's Build.DEVICE and Build.MODEL with a / (slash) is used.

  • Specifications: Build.DEVICE/Build.MODEL
  • Examples: samsung/SM-G991N, google/Pixel_6

iOS​

In iOS apps, the device_name provided by Apple is used as-is.

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