DRM Callback
- Former user (Deleted)
- 김정현 (Unlicensed)
- 현종 조 (Unlicensed)
- admin (Unlicensed)
개요
Kollus 모바일 다운로드 DRM을 이용해 다운로드한 컨텐츠의 ‘재생 재한 횟수’, ‘컨텐츠 만료 기간’, ‘컨텐츠 재생시간'을 설정하여 컨텐츠의 재생을 제어하는 기능을 설명하는 문서입니다. 서비스 모델에 따라 중복 제한으로 설정되어 사용될 수 있습니다.
Expire option
설정 항목의 data-type이나 값이 범위를 벗어나는 경우 컨텐츠 이용에 문제가 발생할 수 있으며, 잘못된 설정 값에 대한 사용 제한을 회수하는 방법은 존재하지 않습니다.
Expire count : 재생 제한 횟수
data-type : integer
range : 0 ~ 1000
0 : unlimited (무제한)
Expire date : 컨텐츠 만료 시간
data-type : integer, unixtime stamp
컨텐츠 재생이 만료될 시간
컨텐츠 재생이 만료될 시간
ex) 2014. 3. 3. 5시 45분 30초 GMT → 1393825531
0 : unlimited (무제한)
최대값 : 2029년 12월 31일 23시 59분 59초 (1893455999)
Expire playtime : 재생시간 제한 (배속의 경우 배속이 적용된 시간 적용)
data-type : integer
range : 0, 60 ~ 604800 (단위:초, 최소: 60초, 최대:1주일)
0 : unlimited (무제한)
DRM callback
DRM 정책을 적용하기 위해서는 채널에 DRM 콜백 URL(DRM callback url)을 설정해야 합니다.
채널에 DRM 콜백 URL을 설정하면 컨텐츠를 다운로드하는 시점에 채널에 설정된 DRM 콜백 URL을 호출하여 반환된 값을 DRM 정책으로 사용하게 됩니다. 이때 다운로드되는 DRM 정책 정보는 JWT Encode 되어 Http Body에 반환 되어야 합니다.
주의:
DRM 콜백 URL이 응답하지 않으면 다운로드가 되지 않습니다.
알고리즘은 HS256만 지원을 하며 Http 헤더에 지정된 헤더(X-KOLLUS-USERKEY)의 값으로 “사용자키"를 함께 전송해야 합니다.
Callback flow
채널에 DRM 콜백 URL을 설정합니다.
ex> http://www.foo.com/auth.php 가 고객사 인증 DRM 서버인 경우
JSON 데이터를 생성 후 JWT로 인코딩 한다.
Kollus mobile player가 http://www.foo.com/auth.php 에 다음의 정보를 POST 전송 합니다.
session_key : 플레이어에서 생성한 요청 확인용 세션키
kind3의 content_expire_reset 경우 요청한 session_key를 확인합니다.
Callback v2가 적용되는 v1.6에서 적용됩니다.
kind : 1 - 3
client_user_id : 고객사 회원 아이디
Media token 생성시 포함된 아이디입니다.
player_id : 고객사 회원이 가지고 있는 단말 아이디
device_name : 고객사 회원이 가지고 있는 단말명
안드로이드, 아이폰에 따라 단말명이 다르게 전달됩니다.
아이폰의 경우 사전에 Apple에서 정의한 문자열로 전달되며 안드로이드의 경우 디바이스명, 모델명이 함께 전달됩니다. 안드로이드의 경우 해당 정보가 없을 경우 NULL을 전달 합니다.
media_content_key : 현재 다운로드하려는 컨텐츠 key 입니다.
채널에 등록된 컨텐츠에 부여된 고유 키입니다.
업로드된 컨텐츠를 여러채널에 등록하면 media_content_key는 모두 다르게 생성됩니다.
고객사 DRM 인증서버는 전달받은 위 정보를 바탕으로 다음의 json 포멧의 data를 JWT의 payload 에 추가하여 Encoding 하고 헤더에 지정된 “시용자키(X-KOLLUS-USERKEY)"를 함께 전송합니다.
(고객사가 인증 정보를 플레이어로 전달할 때 모든 데이터의 자료형은 반드시 기술된대로 integer 형이여야만 합니다.)
device_name 추가 설명
Andoid
안드로이드 어플 개발시 사용되는 Build.DEVICE, Build.MODEL을 /(슬래쉬)로 구분한 문자열로 만들어 사용합니다.
Build.DEVICE+”/”+Build.MODEL
단말기의 특성에 따라 해당 정보는 NULL로 표시될 수 있습니다.
iOS
iOS의 경우 iOS에서 제공하는 device-name을 사용합니다.
Device Type | Product 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 (Wi-Fi) |
iPad2,2 | iPad 2 (GSM) |
iPad2,3 | iPad 2 (CDMA) |
iPad2,4 | iPad 2 (Wi-Fi, revised) |
iPad2,5 | iPad mini (Wi-Fi) |
iPad2,6 | iPad mini (A1454) |
iPad2,7 | iPad mini (A1455) |
iPad3,1 | iPad (3rd gen, Wi-Fi) |
iPad3,2 | iPad (3rd gen, Wi-Fi+LTE Verizon) |
iPad3,3 | iPad (3rd gen, Wi-Fi+LTE AT&T) |
iPad3,4 | iPad (4th gen, Wi-Fi) |
iPad3,5 | iPad (4th gen, A1459) |
iPad3,6 | iPad (4th gen, A1460) |
iPad4,1 | iPad Air (Wi-Fi) |
iPad4,2 | iPad Air (Wi-Fi+LTE) |
iPad4,3 | iPad Air (Rev) |
iPad4,4 | iPad mini 2 (Wi-Fi) |
iPad4,5 | iPad mini 2 (Wi-Fi+LTE) |
iPad4,6 | iPad mini 2 (Rev) |
iPad4,7 | iPad mini 3 (Wi-Fi) |
iPad4,8 | iPad mini 3 (A1600) |
iPad4,9 | iPad mini 3 (A1601) |
iPad5,1 | iPad mini 4 (Wi-Fi) |
iPad5,2 | iPad mini 4 (Wi-Fi+LTE) |
iPad5,3 | iPad Air 2 (Wi-Fi) |
iPad5,4 | iPad Air 2 (Wi-Fi+LTE) |
iPad6,3 | iPad Pro (9.7 inch) (Wi-Fi) |
iPad6,4 | iPad Pro (9.7 inch) (Wi-Fi+LTE) |
iPad6,7 | iPad Pro (12.9 inch, Wi-Fi) |
iPad6,8 | iPad Pro (12.9 inch, Wi-Fi+LTE) |
iPad6,11 | iPad 9.7-Inch 5th Gen (Wi-Fi Only) |
iPad6,12 | iPad 9.7-Inch 5th Gen (Wi-Fi/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) |
DRM Callback 신규 버전 v2이전 1.4까지 제공되던 kind1, kind2, kind3의 호출이 한번의 호출로 통합되어 호출되는 버전으로 변경됩니다. 이전 버전은 사용자의 사용자의 빈번한 호출에 대응하기 용이하지 않다는 다수 고객사의 요청에 따라 추가 되었습니다. 편의상 새로운 버전을 v2로 이전버전을 v1으로 합니다.
Reuest
구분 | Description |
|---|---|
POST | Http POST로 요청합니다. (parameter가 아닙니다.) |
items | JsonArray로 구성된 string 입니다. |
items 항목은 kind1, kind2, kind3의 데이터를 모두 포함한 호출이 될 수 있습니다.
items (JsonArray)
kind1, kind2
구분 | Description |
|---|---|
kind | 1,2 |
client_user_id | 고객사 사용자 ID, media_token 생성시 사용된 client_user_id와 동일합니다. |
player_id | 고객사 사용자가 가지고 있는 단말의 아이디 |
hardware_id | 단말의 hardware 아이디(PC, 입력값이 있으면) |
device_name | 고객사 사용자가 가지고 있는 단말의 모델명 |
media_content_key | Kollus 컨텐츠 unique key |
uservalues | JSON format (VideoGateway 호출시 사용된 uservalue0~9) |
localtime | 단말의 UTC Time |
kind3
구분 | Description |
|---|---|
kind | 3 |
session_key | content_expire_reset 요청시 동일한 session_key를 확인합니다. |
client_user_id | 고객사 사용자 ID, media_token 생성시 사용된 client_user_id와 동일합니다. |
player_id | 고객사 사용자가 가지고 있는 단말의 아이디 |
hardware_id | 단말의 hardware 아이디(PC, 입력값이 있으면) |
device_name | 고객사 사용자가 가지고 있는 단말의 모델명 |
media_content_key | Kollus 컨텐츠 unique key |
start_at | unixtimestamp (localtime) |
uservalues | JSON format (VideoGateway 호출시 사용된 uservalue0~9) |
content_expired | 만료된 컨텐츠 확인 flag( 1 : 만료, 0 : 재생가능) |
check_expired | 체크 유효 시간 만료된 컨텐츠 확인 flag( 1 : 만료, 0 : 재생가능) |
reset_req | 일괄갱신 요청인지 판단( 0 (default), 1 : 일괄갱신) |
expiration_date | 만료 날짜(unixtimestamp) |
localtime | 단말의 UTC Time |
Items Sample
[
{
"kind": 1,
"media_content_key" : "XXX-MEDIA_CONTENTKEY-XXX",
"client_user_id": "XXXXXXX",
"player_id": "xxxxxxxxxxxxxxxx",
"device_name": "XXXXX",
"uservalues": {
"uservalue0": "value0"
}
},
{
"kind": 2,
"media_content_key" : "XXX-MEDIA_CONTENTKEY-XXX",
"client_user_id": "XXXXXXX",
"player_id": "xxxxxxxxxxxxxxxx",
"device_name": "XXXXX",
"uservalues": {
"uservalue0": "value0"
}
},
{
"kind": 3,
"session_key" : "XXX-SESSION_KEY-XXX", ← content_expire_reset 요청시 확인합니다.
"media_content_key" : "XXX-MEDIA_CONTENTKEY-XXX",
"client_user_id": "XXXXXXX",
"player_id": "xxxxxxxxxxxxxxxx",
"device_name": "XXXXX",
"uservalues": {
"uservalue1": "value1"
}
}
]Response
Array은 “data” 필드로 응답 받는다.
kind1
구분 | 필수 | Description |
|---|---|---|
(int) kind | O | 1 |
(string) media_content_key | O | Kollus 컨텐츠 Unique Key |
(int) expiration_date | 만료될 시간의 unixtime stamp | |
(int) expiration_count | 재생 제한 횟수, 예) 10 ← 10번 재생 가능 | |
(int) expiration_playtime | 재생 시간 제한, 예) 60 ← 60초 재생 가능 | |
(int) expiration_playtime_type | 1이면 play 상태일 때 구동 시간으로 제한 | |
(int) result | O | 0 (비정상), 1 (정상) |
(string) message | 0 (비정상)의 경우 message를 추가하면 상황에 따른 메시지가 표시됩니다. | |
(int) | 만료후 갱신 여부 팝업 표시 | |
(int) vmcheck | virtual machine 체크 여부 판단, PC용 | |
(int) check_abuse | DRM kind3 항상 물어보기(0 : 안함(기본값), 1: 체크) | |
(int) offline_bookmark.download | 오프라인일 때 기존 북마크 다운로드 사용 여부 컨텐츠 다운로드 시점의 데이터만 다운로드되며, 이후 서버와 싱크처리 되지 않습니다. 0 : 안함(기본값) 1 : 인덱스만 다운로드 | |
(int) offline_bookmark.readonly | 오프라인일 때 추가/삭제 사용 여부(0 : 사용(기본값), 1: 안함) |
kind2
구분 | 필수 | Description |
|---|---|---|
(int) kind | O | 2 |
(string) media_content_key | O | Kollus 컨텐츠 Unique Key |
(int) content_delete | 0 (삭제하지 않음), 1 (다운로드 받은 파일 삭제) | |
(string) message | 0 (비정상)의 경우나 content_delete이 1(다운로드 받은 파일 삭제)시 message를 추가하면 상황에 따른 메시지가 표시됩니다. | |
(int) check_expiration_date | 사용안함(0), 체크 유효 만료될 시간의 unixtime stamp | |
(int) result | O | 0 (비정상), 1 (정상) |
kind3
구분 | 필수 | Description |
|---|---|---|
(int) kind | O | 3 |
(string) session_key | content_expire_reset 요청시 session_key 확인합니다. | |
(string) media_content_key | O | Kollus 컨텐츠 Unique Key |
(int) start_at | O | Request에 포함된 start_at |
(int) content_expired | 0 (재생가능), 1 (재생 제한) | |
(int) content_delete | 0 (삭제하지 않음), 1 (다운로드 받은 파일 삭제) | |
(int) content_expire_reset | 0 (추가 액션 없음), 1 (expired된 콘텐츠 권한 Reset) | |
(int) expiration_date | 만료될 시간의 unixtime stamp | |
(int) expiration_count | 재생 제한 횟수, 예) 10 ← 10번 재생 가능 | |
(int) expiration_playtime | 재생 시간 제한, 예) 3600 ← 1시간(3600초) 재생 가능 | |
(int) result | O | 0 (비정상), 1 (정상) |
(string) message | 0 (비정상), content_expired이 1(재생 제한) 또는 content_delete이 1(다운로드 받은 파일 삭제) 시 message를 추가하면 상황에 따른 메시지가 표시됩니다. | |
(int) check_abuse | DRM kind3 항상 물어보기(0 : 안함(기본값), 1: 체크) | |
(int) check_expiration_date | 사용안함(0), 체크 유효 만료될 시간의 unixtime stamp * content_expire_reset 옵션이 1일때 재설정 됩니다. |
Response Example
JWT 지원
DRM 정책을 JWT로 반환하는 것을 지원합니다. JWT 웹사이트(https://jwt.io) 에서 공인한 라이브러리를 이용하여 생성된 Token으로 변경하여 반환하도록 추가 되었습니다.
플레이어에 JWT Token으로 반환하는 경우에 지정된 헤더에 사용자키를 포함 시켜 전송해야 합니다.
지정된(X-Kollus-UserKey) 해더로 전송된 사용자키가 일치 하는 경우 플레이어에서 정상적으로 동작하게 됩니다.
JWT Secret, JWT 사용자 키
기존 사용자 키(2)키를 header에 추가하는 것 외에 추가적으로 기존의 JWT scpec에 명시되어 있는 secret key는 보안키(1)를 입력해야 해야 합니다. 고객사는 관련 정보를 아래와 같이 Kollus CMS 에서 확인 할 수 있습니다.
설정 > 서비스 계정 설정
JWT payload
각 callback의 response를 JWT playload에 담아 전송합니다.
Sample
http://jwt.io 에서 제공하는 다양한 언어로 구현된 라이브러리와 예제를 이용해 구현하도록 합니다. JWT 스펙과 동일하나 반환되는 http 헤더에 X-Kollus-UserKey를 이용하여 사용자키를 함께 전송해주셔야 합니다.
(예시) php
Code sample (v1.4 기준)
다음과 같은 고객사의 DB가 구성된 것으로 고려되어 샘플이 구성되어있습니다.
PHP sample
샘플코드
Copyright © CATENOID, lnc. All Rights Reserved.
E-mail. support@catenoid.net | Tel. 1544-4367