DRM 다운로드 콜백
Kollus VOD는 사용자가 콘텐츠를 디바이스에 다운로드하거나, 저장된 파일을 오프라인 상태에서 재생할 때 보안 권한을 검증하는 DRM 다운로드 콜백 기능을 지원합니다. 이를 통해 다운로드 허용 여부, 재생 가능 횟수, 유효 기간 등 정교한 DRM 정책을 실시간으로 제어할 수 있습니다.
유의사항
- 데이터 무결성: 응답 데이터의 타입이 일치하지 않거나 범위를 벗어날 경우, 다운로드 및 재생이 즉시 차단됩니다.
- 설정 회수 불가: 잘못 전송된 만료 일시(
expiration_date) 등의 설정값은 Kollus 시스템 내에서 임의로 수정하거나 취소할 수 없으므로 정확한 값을 전송해야 합니다. - 서버 가용성: 콜백 서버 응답 지연이나 장애 발생 시 서비스 이용이 제한되므로 안정적인 서버 환경 구성을 권장합니다.
콜백 설정 방법
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 다운로드 콜백은 처리 목적에 따라 세 가지 유형으로 구분됩니다.
kind 1(다운로드 승인): 사용자가 다운로드 버튼을 클릭 시 서버에서 권한 및 DRM 정책을 할당합니다.kind 2(다운로드 완료 통보): 디바이스에 파일 저장이 100% 완료된 시점에 결과 데이터를 전송합니다.kind 3(오프라인 재생 권한 확인): 저장된 콘텐츠를 재생할 때마다 재생 권한 및 만료 여부를 확인합니다.
kind 3 구분
kind 값은 콜백마다 별도로 정의됩니다. DRM 다운로드 콜백의 kind 3(오프라인 재생 권한 확인)은 플레이 콜백의 kind 3(최종 재생 승인)과 서로 다른 콜백입니다.
요청 규격
전송 방식
- Method:
POST - Content-Type:
application/x-www-form-urlencoded - Data Format:
items파라미터에JSONArray형태의 JSON 문자열을 포함하여 전송
kind 1, kind 2 요청 파라미터
items
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
kind | integer | ◯ | DRM 다운로드 콜백 유형
|
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 | - | 요청 시점의 디바이스 시각 (Unix timestamp) |
uservalues | JSON string | - | 커스텀 변수 (uservalue0~uservalue99) |
kind 1, kind 2 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"
}
}
]
kind 3 요청 파라미터
items
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
kind | integer | ◯ | DRM 다운로드 콜백 유형
|
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 | - | 재생 만료 여부
|
check_expired | integer | - | 검증 유효 기간 만료 여부
|
reset_req | integer | - | 일괄 업데이트 요청 여부
|
expiration_date | integer | - | 재생 만료 일시 (Unix timestamp) |
localtime | integer | - | 요청 시점의 디바이스 시각 (Unix timestamp) |
kind 3 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) |