Kollus DRM 기반 JWT 가이드

이 문서는 Kollus DRM이 적용된 콘텐츠를 안전하게 재생하기 위해 고객사 서버에서 발행해야 하는 JWT(JSON Web Token)의 상세 규격을 설명합니다.

---

JWT 기술 사양

암호화 알고리즘

보안 무결성을 위해 HMAC SHA-256(HS256) 알고리즘만을 지원합니다.

Header: { "alg": "HS256", "typ": "JWT" }

인증 키

JWT를 생성하고 호출할 때 다음 두 가지 키가 사용됩니다.

보안 키(Security Key)

• 설명: JWT 서명(Signing)에 사용되는 비밀 키입니다. 절대로 외부에 노출되어서는 안 됩니다.
• 위치: Kollus VOD 콘솔 > [서비스 계정] > [사용자 키]

ℹ️참고

보안 키 변경은 Kollus 기술 지원팀(PE, tech_support@catenoid.net)으로 문의해 주세요.

사용자 키(Custom Key)

• 설명: 보안 키를 암호화한 값입니다.
• 위치: Kollus VOD 콘솔 > [서비스 계정] > [사용자 키]
  새로고침 시 값이 변경될 수 있으나, 변경 시점에 표시된 최신 값을 복사해서 사용하면 됩니다.

요청 URL 형식

https://v.kr.kollus.com/s?jwt={생성된_JWT}&custom_key={사용자_키}

⚠️주의

• 표준 Claim 사용 금지: RFC 7519 - Registered Claim Names 사용 시 재생 오류가 발생할 수 있습니다.
• 워터마킹 활성화: 워터마킹(Watermarking) 기능은 기본적으로 비활성화되어 있습니다.
  해당 기능을 활성화하려면 Kollus 영업 담당자(AM, biz@catenoid.net) 또는 기술 지원팀(PE, tech_support@catenoid.net)으로 문의해 주세요.
• iOS 전체 화면 모드: iOS 환경에서 전체 화면 전환 시 iOS Native 플레이어가 사용됩니다.
• 기능 제약 환경: iOS 또는 삼성 브라우저에서 전체 화면으로 재생할 경우, 워터마크 노출 등 Kollus 플레이어의 일부 기능이 동작하지 않을 수 있습니다.

---

JWT 페이로드 상세 규격

필수 옵션 적용 예시

시청자(catenoid)가 특정 콘텐츠(vnCVPVyV)를 재생하기 위한 가장 기본적인 페이로드 구조입니다.

{
  "cuid": "catenoid",
  "expt": 1703980800,
  "mc": [
    {
      "mckey": "vnCVPVyV"
    }
  ]
}

기본 옵션

옵션	타입	필수 여부	기본값	설명
cuid	string	◯	-	시청자(End User) ID. 중복 재생, 북마크, 이어보기(nscreen) 설정 시 기준 식별자(Key)로 사용됩니다. 영문 및 숫자 사용을 권장합니다. 한글이나 특수문자는 차단 내역 조회 시 검색이 제한될 수 있습니다.
expt	integer	◯	-	JWT 만료 시간(Unix TimeStamp). 최댓값은 1893455999입니다. 만료 후에도 서버 시간 오차를 고려하여 최대 1분까지 콘텐츠 접근이 허용될 수 있습니다.
mc	array	◯	-	재생할 콘텐츠 정보를 담은 배열
next_episode	boolean	-	false	다음 회차 콜백 호출 여부 true 설절 시 채널에 지정된 다음 회차 콜백이 호출됩니다.
playback_rates	array	-	-	시청자가 설정 가능한 배속 리스트(2차원 배열)
playcallback_ignore	boolean	-	false	플레이 콜백 무시 여부 true 설정 시 플레이 콜백을 서버로 전송하지 않습니다.

콘텐츠 옵션 (mc 배열 내부 설정)

옵션	타입	필수 여부	기본값	설명
mckey	string	◯	-	콘텐츠 식별자(미디어 콘텐츠 키)
mcpf	string	-	null	인코딩 프로파일 키 값을 입력하지 않으면 재생 디바이스 환경에 최적화된 프로파일이 자동 선택됩니다.
title	string	-	null	콘텐츠 제목 값을 입력하지 않으면 원본 파일의 타이틀 정보가 노출됩니다.
intr	boolean	-	false	인트로 영상 여부 인트로 타입으로 재생 시 이어보기, LMS 콜백, 플레이 콜백 등 일부 기능이 동작하지 않습니다. DRM 다운로드 시 본영상 파일만 다운로드됩니다.
seek	boolean	-	true	탐색(재생 시점 이동) 가능 여부 false 설정 시 시청자의 탐색이 제한됩니다.
seekable_end	integer	-	-1	seek 허용 종료 시점 seek 옵션이 false여도 seekable_end 값이 10이면, 0~10초 구간 내에서는 seek이 허용됩니다.
disable_playrate	boolean	-	false	재생속도(배속) 선택 기능의 비활성화 여부
disable_nscreen	boolean	-	false	이어보기 기능의 비활성화 여부
scroll_event	boolean	-	false	스크롤 이벤트 적용 여부 true: 세로 길이 기준 영상 영역 맞춤 false: 가로 길이 기준 영상 영역 맞춤

재생 구간 설정

옵션	타입	기본값	설명
play_section.start_time	integer	null	재생 구간의 시작 시간(단위: 초)
play_section.end_time	integer	null	재생 구간의 종료 시간(단위: 초)

자막 설정

ℹ️참고

여러 자막 중 특정 자막만 노출하려면 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)

화면에 사용자 식별 정보를 오버레이하여 무단 녹화 및 유출을 방지합니다.

ℹ️참고

• 기능 활성화: 워터마킹 기능은 기본적으로 비활성화되어 있습니다.
  해당 기능을 활성화하려면 Kollus 영업 담당자(AM, biz@catenoid.net) 또는 기술 지원팀(PE, tech_support@catenoid.net)으로 문의해 주세요.
• 위변조 방지: 외부 스크립트(JavaScript Injection)를 통한 워터마크 훼손 방지 기능이 기본 적용됩니다.

옵션	타입	기본값	설명
code_kind	string	-	워터마크로 표시할 식별 정보 "client_user_id" 입력 시 cuid가 표시되며, 그 외의 값은 텍스트 그대로 출력됩니다.
font_size	integer	7	워터마크 텍스트 크기(px)
font_color	string	"FFFFFF"	워터마크 색상(HEX)
alpha	integer	200	워터마크 투명도(0~255)
show_time	integer	1	워터마크가 화면에 노출되는 시간(단위: 초)
hide_time	integer	60	워터마크가 화면에서 숨겨지는 시간(단위: 초)
show_paused	boolean	false	영상 일시정지 상태에서 워터마크 노출 여부
enable_html5_player	boolean	false	Web Player 사용 여부 false일 경우 App Player for Windows로 재생됩니다.

기타 옵션

옵션	타입	기본값	설명
bookmark	boolean	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,
      "seek": false,
      "seekable_end": 30
    }
  ]
}

워터마킹 적용

시청자 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"
    }
  ]
}