Kollus DRM 전용 JWT 규격
이 문서는 Kollus DRM 콘텐츠의 안전한 재생뿐만 아니라 배속 제한, 재생 구간 설정 등 플레이어의 다양한 기능을 제어하기 위해 고객사 서버에서 발행해야 하는 JWT(JSON Web Token)의 상세 규격을 설명합니다.
Kollus DRM 전용 JWT 규격은 암호화되지 않은 일반 콘텐츠의 재생 URL 생성 시에도 동일하게 적용하여 플레이어의 비즈니스 로직을 제어할 수 있습니다.
JWT 기술 사양
암호화 알고리즘
Kollus VOD는 HMAC SHA-256(HS256) 알고리즘만을 지원합니다.
Header: { "alg": "HS256", "typ": "JWT" }
인증 키
JWT 생성 및 호출 시 다음 두 가지 키를 사용합니다.
보안 키
- 설명: JWT 서명(Signing) 및 검증에 사용되는 비밀 키입니다. 외부 유출에 주의하세요.
- 확인 경로:
Kollus VOD 콘솔 > [서비스 계정] > [사용자 키]
ℹ️참고
보안 키 변경은 기술 지원팀(PE, tech_support@catenoid.net)으로 문의해 주세요.
사용자 키 (custom_key)
- 설명: 보안 키를 암호화한 값으로, 보안 키와 함께 인증(JWT)에 사용됩니다.
- 확인 경로:
Kollus VOD 콘솔 > [서비스 계정] > [사용자 키]
새로고침 시 값이 업데이트될 수 있으며, 사용 시점의 최신 값을 복사하여 적용해야 합니다.
요청 URL 형식
https://v.kr.kollus.com/s?jwt={JWT}&custom_key={CUSTOM_KEY}
⚠️주의
- 표준 Claim 사용 제한: RFC 7519 - Registered Claim Names 규격의 Claim 사용 시 오류가 발생할 수 있습니다.
- 워터마킹 활성화: 워터마킹(Watermarking) 기능은 기본적으로 비활성화되어 있습니다. 해당 기능을 활성화하려면 영업 담당자(AM, biz@catenoid.net) 또는 기술 지원팀(PE, tech_support@catenoid.net)으로 문의해 주세요.
- iOS 전체 화면 모드: iOS 환경에서 전체 화면 전환 시 iOS Native 플레이어가 구동됩니다.
- 기능 제약 환경: iOS 또는 삼성 브라우저에서 전체 화면 재생 시, 워터마크 노출 등 Kollus 플레이어 기능의 동작이 제한될 수 있습니다.
JWT 페이로드 상세 규격
필수 옵션 적용 예시
시청자(catenoid)가 특정 콘텐츠(vnCVPVyV)를 재생하기 위한 기본 페이로드(Payload) 구조입니다.
{
"cuid": "catenoid",
"expt": 1703980800,
"mc": [
{
"mckey": "vnCVPVyV"
}
]
}
기본 옵션
| 옵션 | 타입 | 필수 여부 | 기본값 | 설명 |
|---|---|---|---|---|
cuid | string | ◯ | - | 시청자 ID
|
expt | integer | ◯ | - | JWT 만료 일시 (형식: Unix Timestamp, 최댓값: 1893455999)
|
mc | array | ◯ | - | 재생할 콘텐츠 정보를 포함하는 배열 |
next_episode | boolean | - | false | 다음 회차 콜백 호출 여부
|
playback_rates | array | - | - | 시청자가 선택 가능한 배속 리스트 (2차원 배열) |
playcallback_ignore | boolean | - | false | 플레이 콜백 전송 무시 여부
|
콘텐츠 옵션 (mc 배열 내부 설정)
ℹ️식별 키(Key) 정보
식별 키 정보는 아래 문서를 참고하세요.
| 옵션 | 타입 | 필수 여부 | 기본값 | 설명 |
|---|---|---|---|---|
mckey | string | ◯ | - | 콘텐츠 식별자 (미디어 콘텐츠 키) |
mcpf | string | - | null | 인코딩 프로파일 키
|
title | string | - | null | 콘텐츠 제목
|
intr | boolean | - | false | 인트로/아웃트로 영상 여부
|
seek | boolean | - | true | 재생 시점 이동(탐색) 가능 여부 |
seekable_end | integer | - | -1 | 탐색 허용 종료 시점 (s)
|
disable_playrate | boolean | - | false | 배속 선택 기능 비활성화
|
disable_nscreen | boolean | - | false | 이어보기 기능 비활성화
|
scroll_event | boolean | - | false | 스크롤 이벤트 적용 여부
|
재생 구간 설정
| 옵션 | 타입 | 기본값 | 설명 |
|---|---|---|---|
play_section.start_time | integer | null | 재생 구간 시작 시점 (s) |
play_section.end_time | integer | null | 재생 구간 종료 시점 (s) |
자막 설정
ℹ️참고
특정 자막만 노출하려면 filter와 show_by_filter 옵션을 모두 true로 설정하세요.
| 옵션 | 타입 | 기본값 | 설명 |
|---|---|---|---|
subtitle_policy.filter.name | string | null | 자막 필터 - 자막 이름 |
subtitle_policy.filter.language_code | string | null | 자막 필터 - 언어 코드 |
subtitle_policy.filter_main.name | string | null | 메인 자막 필터 - 자막 이름 |
subtitle_policy.filter_main.language_code | string | null | 메인 자막 필터 - 언어 코드 |
subtitle_policy.filter_sub.name | string | null | 서브 자막 필터 - 자막 이름 |
subtitle_policy.filter_sub.language_code | string | null | 서브 자막 필터 - 언어 코드 |
subtitle_policy.show_by_filter | boolean | false | 필터링 기준에 따른 자막 노출 여부 |
subtitle_policy.is_showable | boolean | false | 자막 노출 여부 |
워터마킹 (Watermarking)
화면에 사용자 식별 정보를 오버레이하여 무단 녹화 및 유출을 방지합니다.
ℹ️참고
- 기능 활성화: 워터마킹 기능은 기본적으로 비활성화되어 있습니다. 해당 기능을 활성화하려면 영업 담당자(AM, biz@catenoid.net) 또는 기술 지원팀(PE, tech_support@catenoid.net)으로 문의해 주세요.
- 위변조 방지: 외부 스크립트(JavaScript Injection)를 통한 워터마크 훼손 방지 기능 이 기본 적용됩니다.
| 옵션 | 타입 | 기본값 | 설명 |
|---|---|---|---|
video_watermarking_code_policy.code_kind | string | - | 워터마크 표시 텍스트
|
video_watermarking_code_policy.font_size | integer | 7 | 워터마크 텍스트 크기 (px) |
video_watermarking_code_policy.font_color | string | "FFFFFF" | 워터마크 색상 (HEX) |
video_watermarking_code_policy.alpha | integer | 200 | 워터마크 투명도 (0~255) |
video_watermarking_code_policy.show_time | integer | 1 | 워터마크 노출 지속 시간 (s) |
video_watermarking_code_policy.hide_time | integer | 60 | 워터마크 숨김 지속 시간 (s) |
video_watermarking_code_policy.show_paused | boolean | false | 일시정지 상태에서 워터마크 노출 여부 |
video_watermarking_code_policy.enable_html5_player | boolean | false | Kollus Web Player 사용 여부
|
기타 옵션
| 옵션 | 타입 | 기본값 | 설명 |
|---|---|---|---|
bookmark | boolean | true | 북마크 버튼 노출 여부 |
사용 예제
인트로 + 본 영상 + 아웃트로 연속 재생
인트로, 본 영상, 아웃트로를 하나의 끊김 없는 콘텐츠로 재생되도록 구성한 예제입니다.
{
"cuid": "{END_USER_ID}",
"expt": 1735660800,
"mc": [
{
"mckey": "gDV2B1ZG",
"intr": true
},
{
"mckey": "vnCVPVyV"
},
{
"mckey": "eBzkZtzG",
"intr": true
}
]
}
인트로 영상 후 본 영상 연속 재생
인트로의 탐색(Seek)을 금지하고 본 영상으로 자동 전환되도록 구성한 예제입니다.
{
"cuid": "{END_USER_ID}",
"expt": 1735660800,
"mc": [
{
"mckey": "gDV2B1ZG",
"intr": true,
"seek": false
},
{
"mckey": "vnCVPVyV"
}
]
}
0~30초 구간만 탐색(Seek) 허용
전체 탐색은 차단하되 도입부(30초)만 탐색 가능하게 설정하여 맛보기 영상용으로 활용하는 예제입니다.
{
"cuid": "{END_USER_ID}",
"expt": 1735660800,
"mc": [
{
"mckey": "gDV2B1ZG",
"intr": true,
"seekable_end": 30,
"seek": false
}
]
}
시청 완료 구간만 탐색 허용
시청 완료 구간 내 탐색만 허용하고 미시청 구간으로의 임의 탐색을 제한하는 예제입니다.
{
"cuid": "{END_USER_ID}",
"expt": 1735660800,
"mc": [
{
"mckey": "vnCVPVyV",
"seekable_end": 1,
"seek": false
}
]
}
워터마킹 적용
시청자 ID(cuid)를 화면에 3초간 노출하고 300초(5분)간 숨기는 보안 정책 적용 예제입니다.
{
"cuid": "{END_USER_ID}",
"expt": 1735660800,
"video_watermarking_code_policy": {
"code_kind": "client_user_id",
"font_size": 10,
"font_color": "FFFFFF",
"alpha": 128,
"show_time": 3,
"hide_time": 300
},
"mc": [
{
"mckey": "vnCVPVyV"
}
]
}
ℹ️샘플 코드 참조
전체 예제 코드(PHP)는 Kollus GitHub 저장소에서 확인할 수 있습니다.