Skip to main content

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

JWT Payload 상세 규격​

필수 옵션 적용 예시​

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

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

기본 옵션​

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

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

관련 정보

키(Key/ID) 정보는 아래 문서를 참고하세요.

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

콘텐츠 노출 구간 설정​

Kollus VOD는 원본 파일의 물리적 편집(자르기, 합치기 등) 기능을 제공하지 않지만, 등록된 콘텐츠의 특정 구간만 시청자에게 노출되도록 설정할 수 있습니다.

  • 기능 정의: 원본 영상 내에서 시청이 가능한 시작 시점(start_time)과 종료 시점(end_time)을 지정하여 배포하는 기능입니다.
  • 핵심 특징
    • 동영상 편집 불가: 업로드 완료된 원본 영상 파일 자체를 자르거나 합치는 등 데이터 수준의 물리적 편집은 지원하지 않습니다.
    • 특정 구간 배포 가능: 설정된 구간 외의 영상은 시청자 플레이어에 로드되지 않으며, 오직 지정된 특정 부분만 시청자에게 노출됩니다.
    • 유연한 관리: 원본 파일을 복제하거나 재업로드할 필요 없이, 설정값 변경만으로 하나의 파일을 여러 개의 게시물로 활용할 수 있습니다.
옵션타입기본값설명
play_section.start_timeintegernull재생 구간 시작 시점 (sec)
play_section.end_timeintegernull재생 구간 종료 시점 (sec)

자막 설정​

구현 가이드

특정 자막만 노출하려면 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워터마크 노출 지속 시간 (sec)
video_watermarking_code_policy.hide_timeinteger60워터마크 숨김 지속 시간 (sec)
video_watermarking_code_policy.show_pausedbooleanfalse일시정지 상태에서 워터마크 노출 여부
video_watermarking_code_policy.enable_html5_playerbooleanfalseKollus Web Player 사용 여부
  • false 설정 시 App Player for Windows로 재생됩니다.
PHP 구현 예제
<?php
/**
* base64_urlencode
*
* @param string $str
* @return string
*/
function base64_urlencode($str) {
    return rtrim(strtr(base64_encode($str), '+/', '-_'), '=');
}

/**
* jwt_encode
*
* @param array $payload
* @param string $key
* @return string
*/
function jwt_encode($payload, $key) {
    $jwtHead = base64_urlencode(json_encode(array('typ' => 'JWT', 'alg' => 'HS256')));
    $jsonPayload = base64_urlencode(json_encode($payload));
    $signature = base64_urlencode(hash_hmac('SHA256', $jwtHead . '.' . $jsonPayload, $key, true));

    return $jwtHead . '.' . $jsonPayload . '.' . $signature;
}

$securityKey = 'SECURITY_KEY';
$customKey = 'CUSTOM_KEY';
$mediaContentKey = 'MEDIA_CONTENT_KEY';
$clientUserId = 'CLIENT_USER_ID';
$expireTime =  7200; // 120 minutes
$mediaItems = array(
  array(
        'media_content_key' => $mediaContentKey,
    ),
);

$payload = array(
    'mc' => array(),
    'cuid' => $clientUserId,
    'expt' => time() + $expireTime,
  'video_watermarking_code_policy' => 
      array(
        'code_kind' => '2930451',
        'font_size' => 20,
        'font_color' => 'ffffff',
        'show_time' => 10,
        'hide_time' => 1,
        'alpha' => 255,
        'enable_html5_player' => true
      ),
);

foreach ($mediaItems as $mediaItem) {
    $mcClaim = array();
    $mcClaim['mckey'] = $mediaItem['media_content_key'];
    $payload['mc'][] = $mcClaim;
}

$jwtToken = jwt_encode($payload, $securityKey);

$webTokenURL = 'http://v.kr.kollus.com/s?jwt=' . $jwtToken . '&custom_key=' . $customKey;
?>

<!DOCTYPE html>
<html lang="en">
<body>
    <iframe width="840" height="472" src="<?php echo $webTokenURL; ?>" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>
</body>
</html>

기타 옵션​

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

사용 예제​

인트로 + 본 영상 + 아웃트로 연속 재생​

인트로, 본 영상, 아웃트로를 하나의 끊김 없는 콘텐츠로 재생되도록 구성한 예제입니다.

{
  "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 저장소에서 확인할 수 있습니다.