본문으로 건너뛰기

보안 라이브 시청 URL 생성 (JWT)

라이브 방송에 보안 기능을 적용하려면 고객사 서버에서 유효한 JWT(JSON Web Token)를 생성하여 플레이어 호출 시 전달해야 합니다.

이 문서는 권한이 인증된 사용자(End User)만 방송을 시청할 수 있도록 제한하고, 중복 재생 차단 등의 보안 기능을 적용하기 위한 JWT의 상세 규격을 설명합니다.

JWT 기술 사양​

암호화 알고리즘​

Kollus Live는 HMAC SHA-256(HS256) 알고리즘만을 지원합니다.

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

인증 키​

JWT 생성 및 호출 시 다음 두 가지 키를 사용합니다.

보안 키​

  • 설명: JWT 서명(Signing) 및 검증에 사용되는 비밀 키입니다. 외부 유출에 주의하세요.
  • 확인 경로: Kollus Live 콘솔 > [설정] > [기본 정보] > [서비스 계정] 탭
ℹ️참고

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

사용자 키 (CUSTOM_KEY)​

  • 설명: 보안 키를 암호화한 값으로, 보안 키와 함께 인증(JWT)에 사용됩니다.
  • 확인 경로: Kollus Live 콘솔 > [설정] > [기본 정보] > [서비스 계정] 탭

요청 URL 형식​

https://v-live-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)가 특정 채널(vouww6hjt9xy9dnV)을 시청하기 위한 기본 페이로드(Payload) 구조입니다.

{
  "client_user_id": "catenoid",
  "expire_time": 1735660800,
  "live_media_channel_key": "vouww6hjt9xy9dnV"
}

기본 옵션​

옵션타입필수 여부기본값설명
client_user_id (cuid)string◯-시청자 ID
  • 중복 재생 차단 및 녹화/캡처 차단 설정 시 기준 식별자로 사용됩니다.
  • 영문 및 숫자 사용을 권장합니다. 한글이나 특수문자는 차단 내역 조회 시 검색이 제한될 수 있습니다.
expire_time (expt)integer◯-JWT 만료 일시 (형식: Unix Timestamp, 최댓값: 1893455999)
  • 만료 후에도 서버 시간 오차를 고려하여 최대 1분까지 접근이 허용될 수 있습니다.
live_media_channel_key (lmckey)string◯-채널 식별자 (채널 키)
client_user_namestring--채팅창에 노출될 시청자의 닉네임
client_user_imagestring--닉네임 옆에 노출될 이미지 URL (https 필수)
play_exptinteger-현재 시각 + 2일라이브 방송 접근 유효 시간
live_media_profile_key (lmpf)string--인코딩 프로파일 키 (미입력 시 ABR 적용)
titlestring--플레이어에 표시될 방송 제목 (미입력 시 기존 방송 제목 표시)

채팅 옵션​

옵션타입기본값설명
chatting_policy.is_visiblebooleantrue채팅창 노출 여부
chatting_policy.is_adminbooleanfalse채팅 관리자 권한 부여 여부

채팅 UI 옵션​

옵션타입기본값설명
chat_font_urlstring-웹 폰트 URL (1개만 지원, 브라우저별 지원 확장자 확인 필요)
chat_font_namestring-폰트 이름 (30자 이하, chat_font_url에 포함된 이름과 동일하게 입력 권장)
chat_font_weightstring-폰트 굵기 (chat_font_url에 포함된 굵기만 적용됨)
chat_font_colorstring-채팅 텍스트 색상 (HEX)
chat_background_colorstring-채팅창 배경 색상 (HEX)
chat_tab_font_colorstring-채팅창 탭 메뉴 텍스트 색상 (HEX)
chat_tab_background_colorstring-채팅창 탭 메뉴 배경 색상 (HEX)

워터마킹(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.enable_html5_playerbooleanfalseKollus Web Player 사용 여부
  • false 설정 시 App Player for Windows로 재생됩니다.

사용 예제​

채팅 기능 커스텀​

{
    "client_user_id": "catenoid",
    "client_user_name": "guest_1",
    "expire_time": 1735660800,
    "live_media_channel_key": "vouww6hjt9xy9dnV",
    "chatting_policy": {
        "is_visible": true,
        "is_admin": false,
        "position": "right"
    },
    "chat_font_weight": "700",
    "chat_font_color": "ffffff",
    "chat_background_color": "333333",
    "chat_tab_font_color": "00ff00",
    "chat_tab_background_color": "777777"
}

워터마킹 적용​

{
    "client_user_id": "catenoid",
    "live_media_channel_key": "vouww6hjt9xy9dnV",
    "expire_time": 1735660800,
    "client_user_name": "guest_1",
    "video_watermarking_code_policy": {
        "code_kind": "catenoid",
        "font_size": 7,
        "font_color": "FFFFFF",
        "show_time": 1,
        "hide_time": 500,
        "alpha": 50,
        "enable_html5_player": false
    }
}