DRM 다운로드 콜백

Kollus VOD는 사용자가 콘텐츠를 디바이스에 다운로드하거나, 저장된 파일을 오프라인 상태에서 재생할 때 보안 권한을 검증하는 DRM 다운로드 콜백 기능을 지원합니다. 이를 통해 다운로드 허용 여부, 재생 가능 횟수, 유효 기간 등 정교한 DRM 정책을 실시간으로 제어할 수 있습니다.

유의 사항

데이터 무결성: 응답 데이터의 타입이 일치하지 않거나 범위를 벗어날 경우, 다운로드 및 재생이 즉시 차단됩니다.
설정 회수 불가: 잘못 전송된 만료 일시(expiration_date) 등의 설정값은 Kollus 시스템 내에서 임의로 수정하거나 취소할 수 없으므로 정확한 값을 전송해야 합니다.
서버 가용성: 콜백 서버 응답 지연이나 장애 발생 시 서비스 이용이 제한되므로 안정적인 서버 환경 구성을 권장합니다.

콜백 설정 방법

콜백 URL은 Kollus VOD 콘솔에서 설정할 수 있습니다.

상세 가이드: 콜백 연동 - DRM 다운로드 콜백

콜백 흐름

주의

응답 규격: 콜백 서버의 응답 데이터는 반드시 JWT(JSON Web Token) 형식으로 반환되어야 합니다.
헤더 인증: HTTP 응답 헤더에 X-KOLLUS-USERKEY: {CUSTOM_KEY}를 반드시 포함해야 합니다.
- 확인 경로: Kollus VOD 콘솔 > [서비스 계정] > [사용자 키]
데이터 타입: JSON 내 모든 정수형 필드(expiration_date, result, content_expired 등)는 integer 타입으로 전달해야 합니다. ("1"과 같이 string 타입으로 전송 시 처리 실패)

콜백 유형

DRM 다운로드 콜백은 처리 목적에 따라 세 가지 유형으로 구분됩니다.

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 다운로드 콜백 유형 `1`: 다운로드 승인 `2`: 다운로드 완료 통보
`client_user_id`	`string`	◯	시청자 ID (JWT 생성 시 입력한 `client_user_id`)
`player_id`	`string`	◯	Kollus 플레이어 고유 ID
`hardware_id`	`string`	-	하드웨어 ID (Windows 환경 등 식별 가능한 값이 존재하는 경우 제공)
`device_name`	`string`	-	디바이스 모델명
`media_content_key`	`string`	◯	미디어 콘텐츠 키
`localtime`	`integer`	-	디바이스 기준 UTC 시간
`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 다운로드 콜백 유형 `3`: 오프라인 재생 권한 확인
`session_key`	`string`	◯	만료 일시 갱신(Renewal)을 위한 세션 키 (`content_expire_reset` 요청 시 정합성 검증에 사용)
`client_user_id`	`string`	◯	시청자 ID (JWT 생성 시 입력한 `client_user_id`)
`player_id`	`string`	◯	Kollus 플레이어 고유 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`	-	디바이스 기준 UTC 시간

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 다운로드 콜백 응답은 데이터 보안과 무결성을 위해 반드시 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 다운로드 콜백 유형 `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 다운로드 콜백 유형 `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 다운로드 콜백 유형 `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
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
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

유의 사항​

콜백 설정 방법​

콜백 흐름​

콜백 유형​

요청 규격​

전송 방식​

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​

유의 사항

콜백 설정 방법

콜백 흐름

콜백 유형

요청 규격

전송 방식

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