보안 방송 URL 생성 (JWT)
라이브 방송에 보안 기능을 적용하려면 고객사 서버에서 유효한 JWT(JSON Web Token)를 생성하여 플레이어 호출 시 전달해야 합니다.
이 문서는 권한이 인증된 사용자만 방송을 시청할 수 있도록 제한하고, 중복 재생 차단 등의 보안 기능을 적용하기 위한 JWT의 상세 규격을 설명합니다.
JWT 기술 사양
암호화 알고리즘
Kollus Live는 HMAC SHA-256(HS256) 알고리즘만을 지원합니다.
Header: { "alg": "HS256", "typ": "JWT" }
인증 키
JWT 생성 및 호출 시 다음 두 가지 키를 사용합니다.
보안 키
- 설명: JWT 서명(Signing) 및 검증에 사용되는 비밀 키입니다. 외부 유출에 주의하세요.
- 확인 경로: Kollus Live 콘솔 > [설정] > [기본 정보] > [서비스 계정] 탭
- 보안 키 변경: 기술 지원팀(tech_support@kollus.com)으로 문의해 주세요.
사용자 키 (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) 기능은 기본적으로 비활성화되어 있습니다. 해당 기능을 활성화하려면 기술 지원팀(tech_support@kollus.com) 또는 영업 담당자(AM)에게 문의해 주세요.
- iOS 전체 화면 모드: iOS 환경에서 전체 화면 전환 시 iOS Native 플레이어가 구동됩니다.
- 기능 제약 환경: iOS 또는 삼성 브라우저에서 전체 화면 재생 시, 워터마크 노출 등 Kollus 플레이어 기능의 동작이 제한될 수 있습니다.
JWT Payload 상세 규격
필수 옵션 적용 예시
시청자(catenoid)가 특정 채널(vouww6hjt9xy9dnV)을 시청하기 위한 기본 Payload 구조입니다.
{
"client_user_id": "catenoid",
"expire_time": 1893455999,
"live_media_channel_key": "vouww6hjt9xy9dnV"
}
기본 옵션
관련 정보
키(Key) 정보는 인증 및 API 키 문서를 참고하세요.
| 옵션 | 타입 | 필수 여부 | 기본값 | 설명 |
|---|---|---|---|---|
client_user_id (cuid) | string | ◯ | - | 시청자 ID
|
expire_time (expt) | integer | ◯ | - | JWT 만료일 (Unix timestamp)
|
live_media_channel_key (lmckey) | string | ◯ | - | 채널 고유 식별자 (채널 키) |
client_user_name | string | - | - | 채팅창에 노출될 시청자의 닉네임 |
client_user_image | string | - | - | 닉네임 옆에 노출될 이미지 URL (https 필수) |
play_expt | integer | - | 현재 시각 + 2일 | 라이브 방송 접근 유효 시간 |
live_media_profile_key (lmpf) | string | - | - | 인코딩 프로파일 키 (미입력 시 ABR 적용) |
title | string | - | - | 플레이어에 표시될 방송 제목 (미입력 시 기존 방송 제목 표시) |
채팅 옵션
| 옵션 | 타입 | 기본값 | 설명 |
|---|---|---|---|
chatting_policy.is_visible | boolean | true | 채팅창 노출 여부 |
chatting_policy.is_admin | boolean | false | 채팅 관리자 권한 부여 여부 |
chatting_policy.position | string | "right" | 채팅창 위치
|
채팅 UI 옵션
| 옵션 | 타입 | 기본값 | 설명 |
|---|---|---|---|
chat_font_url | string | - | 웹 폰트 URL (1개만 지원, 브라우저별 지원 확장자 확인 필요) |
chat_font_name | string | - | 폰트 이름 (30자 이하, chat_font_url에 포함된 이름과 동일하게 입력 권장) |
chat_font_weight | string | - | 폰트 굵기 (chat_font_url에 포함된 굵기만 적용됨) |
chat_font_color | string | - | 채팅 텍스트 색상 (hex) |
chat_background_color | string | - | 채팅창 배경 색상 (hex) |
chat_tab_font_color | string | - | 채팅창 탭 메뉴 텍스트 색상 (hex) |
chat_tab_background_color | string | - | 채팅창 탭 메뉴 배경 색상 (hex) |
워터마킹
화면에 사용자 식별 정보를 오버레이하여 무단 녹화 및 유출을 방지합니다.
참고
- 기능 활성화 안내: 워터마킹 기능은 기본적으로 비활성화되어 있습니다. 해당 기능을 활성화하려면 기술 지원팀(tech_support@kollus.com) 또는 영업 담당자(AM)에게 문의해 주세요.
- 위변조 방지: 외부 스크립트(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 | 워터마크 노출 지속 시간 (sec) |
video_watermarking_code_policy.hide_time | integer | 60 | 워터마크 숨김 지속 시간 (sec) |
video_watermarking_code_policy.enable_html5_player | boolean | false | Kollus Web Player 사용 여부
|
사용 예제
채팅 기능 커스텀
{
"client_user_id": "catenoid",
"client_user_name": "guest_1",
"expire_time": 1893455999,
"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": 1893455999,
"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
}
}