본문으로 건너뛰기

Kollus DRM 전용 JWT 규격

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

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 플레이어 기능의 동작이 제한될 수 있습니다.

식별 키 정보​

요청 URL에 포함되는 식별 키 정보는 서비스 연동 키 문서를 참고하세요.

JWT 페이로드 상세 규격​

필수 옵션 적용 예시​

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

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

기본 옵션​

옵션타입필수 여부기본값설명
cuidstring◯-시청자 ID
  • 중복 재생, 북마크, 이어보기(nscreen) 설정의 기준값입니다.
  • 영문 및 숫자 사용을 권장합니다. 한글이나 특수문자 사용 시 차단 내역 검색이 제한될 수 있습니다.
exptinteger◯-JWT 만료 일시 (형식: Unix Timestamp, 최댓값: 1893455999)
  • 만료 후에도 서버 시간 오차를 고려하여 최대 1분까지 콘텐츠 접근이 허용될 수 있습니다.
mcarray◯-재생할 콘텐츠 정보를 포함하는 배열
next_episodeboolean-false다음 회차 콜백 호출 여부
  • true 설정 시 채널에 지정된 다음 회차 콜백이 호출됩니다.
playback_ratesarray--시청자가 선택 가능한 배속 리스트 (2차원 배열)
playcallback_ignoreboolean-false플레이 콜백 전송 무시 여부
  • true 설정 시 플레이 콜백을 서버로 전송하지 않습니다.

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

옵션타입필수 여부기본값설명
mckeystring◯-콘텐츠 식별자 (미디어 콘텐츠 키)
mcpfstring-null 인코딩 프로파일 키
  • 미입력 시 재생 환경에 최적화된 프로파일이 자동 선택됩니다.
titlestring-null콘텐츠 제목
  • 미입력 시 원본 파일 제목이 노출됩니다.
intrboolean-false인트로 영상 여부
  • 인트로 타입 재생 시 이어보기, LMS 콜백 등 일부 기능이 제한됩니다.
  • DRM 다운로드 시 본 영상 파일만 다운로드됩니다.
seekboolean-true재생 시점 이동(탐색) 가능 여부
seekable_endinteger--1탐색 허용 종료 시점 (초)
  • seek 옵션이 false인 경우에도 seekable_end가 10이면, 0~10초 구간 내에서는 탐색이 허용됩니다.
disable_playrateboolean-false배속 선택 기능 비활성화
  • true 설정 시 배속 선택 기능이 비활성화됩니다.
disable_nscreenboolean-false이어보기 기능 비활성화
  • true 설정 시 이어보기 기능이 비활성화됩니다.
scroll_eventboolean-false스크롤 이벤트 적용 여부
  • true: 세로 길이 기준 영상 영역 맞춤
  • false: 가로 길이 기준 영상 영역 맞춤

재생 구간 설정​

옵션타입기본값설명
play_section.start_timeintegernull재생 구간 시작 시점 (초)
play_section.end_timeintegernull재생 구간 종료 시점 (초)

자막 설정​

ℹ️참고

특정 자막만 노출하려면 filter와 show_by_filter 옵션을 모두 true로 설정하세요.

옵션타입기본값설명
subtitle_policy.filter.namestringnull자막 필터 - 자막 이름
subtitle_policy.filter.language_codestringnull자막 필터 - 언어 코드
subtitle_policy.filter_main.namestringnull메인 자막 필터 - 자막 이름
subtitle_policy.filter_main.language_codestringnull메인 자막 필터 - 언어 코드
subtitle_policy.filter_sub.namestringnull서브 자막 필터 - 자막 이름
subtitle_policy.filter_sub.language_codestringnull서브 자막 필터 - 언어 코드
subtitle_policy.show_by_filterbooleanfalse필터링 기준에 따른 자막 노출 여부
subtitle_policy.is_showablebooleanfalse자막 노출 여부

워터마킹 (Watermarking)​

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

ℹ️참고
  • 기능 활성화: 워터마킹 기능은 기본적으로 비활성화되어 있습니다. 해당 기능을 활성화하려면 영업 담당자(AM, biz@catenoid.net) 또는 기술 지원팀(PE, tech_support@catenoid.net)으로 문의해 주세요.
  • 위변조 방지: 외부 스크립트(JavaScript Injection)를 통한 워터마크 훼손 방지 기능이 기본 적용됩니다.
옵션타입기본값설명
video_watermarking_code_policy.code_kindstring-워터마크 표시 텍스트
  • "client_user_id" 입력 시 cuid가 출력되고, 일반 문자열 입력 시 해당 텍스트가 그대로 출력됩니다.
video_watermarking_code_policy.font_sizeinteger7워터마크 텍스트 크기 (px)
video_watermarking_code_policy.font_colorstring"FFFFFF"워터마크 색상 (HEX)
video_watermarking_code_policy.alphainteger200워터마크 투명도 (0~255)
video_watermarking_code_policy.show_timeinteger1워터마크 노출 지속 시간 (초)
video_watermarking_code_policy.hide_timeinteger60워터마크 숨김 지속 시간 (초)
video_watermarking_code_policy.show_pausedbooleanfalse일시정지 상태에서 워터마크 노출 여부
video_watermarking_code_policy.enable_html5_playerbooleanfalseKollus Web Player 사용 여부
  • false 설정 시 App Player for Windows로 재생됩니다.

기타 옵션​

옵션타입기본값설명
bookmarkbooleantrue북마크 버튼 노출 여부

사용 예제​

인트로 영상 후 본 영상 연속 재생​

인트로의 탐색(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"
    }
  ]
}