플레이어 호출 옵션 (Query String)
이 문서는 재생 URL 뒤에 Query String 파라미터를 추가하여 플레이어의 동작과 UI를 세밀하게 제어하는 방법을 설명합니다.
Query String 형식
재생 URL에 파라미터를 추가하는 규칙은 다음과 같습니다.
https://v.kr.kollus.com/{MEDIA_CONTENT_KEY}?{KEY}={VALUE}&{KEY2}={VALUE2}
- 구분자: URL 끝에
?를 붙입니다. 여러 옵션을 연결할 때는&를 구분자로 사용합니다. - 플래그(Flag) 형식: 별도의 값(
VALUE)이 필요 없는 옵션은 키(KEY)만 입력합니다. (예:?autoplay&mute) - 인코딩: 파라미터 값에 한글, 특수문자, 공백이 포함된 경우, 반드시 해당 값을 UTF-8 URL 인코딩(URL Encoding) 처리하여 전달해야 합니다.
Kollus 플레이어 구분
| 표기 | 플레이어 이름 | 특징 |
|---|---|---|
| v3e | App Player for Windows | 설치형 Agent 방식 플레이어 |
| v3h | Html5 Player for PC | 설치형 HTML5 Agent 방식 플레이어 |
| v3 | Html5 Player for PC (Hybrid) | Microsoft Edge 또는 Chrome 45 이상에서 암호화 콘텐츠 재생 시 적용되는 하이브리드 HTML5 플레이어 |
| v4 | Html5 Player for All | 비암호화 콘텐츠 전용 비설치형 HTML5 플레이어 |
| v5 | Web Player | 설치형과 비설치형의 장점을 결합한 차세대 통합 웹 플레이어 |
| iOS | App Player for iOS | iOS 전용 앱 플레이어 |
| Android | App Player for Android | Android 전용 앱 플 레이어 |
전체 옵션
ℹ️플레이어 안내
Kollus 플레이어에 대한 상세 설명은 아래 문서를 참고하세요.
재생
| 파라미터 | 타입 | 지원 플레이어 | 설명 |
|---|---|---|---|
autoplay (a) | null | All | 자동 재생 설정 (모바일 환경은 기본 활성화) |
mute | null | All | 음소거 상태로 재생 시작 |
t | integer | All | 지정 시점(s)부터 재생 및 이어보기 팝업 노출 |
s | integer | All | 지정 시점(s)부터 재생 및 이어보기 팝업 없음 |
title | string | All | 콘텐츠 제목 강제 지정 |
pf | string | All | 인코딩 프로파일(화질) 강제 지정 |
ℹ️참고
- 재생 옵션 예외:
t또는s값이 영상의 시작/종료 10초 이내인 경우, 시스템 안정성을 위해 영상의 처음(0초)부터 재생됩니다. - 브라우저 자동 재생 정책: Chrome 및 최신 브라우저는 음성이 포함된 영상의 자동 재생을 기본 차단합니다. 상세 내용은 Chrome의 자동 재생 정책을 참고하세요.
다운로드
| 파라미터 | 타입 | 지원 플레이어 | 설명 |
|---|---|---|---|
download | null | Mobile, v3e, v3h | 다운로드 모드 활성화 |
mobile_folder_download | string | Mobile | 모바일 다운로드 폴더 경로 지정 |
pc_folder_download | string | v3e, v3h | PC 다운로드 폴더 경로 지정 |
filename | string | All | R링크, SR링크 사용 시 저장될 파일 이름 지정 |
ℹ️참고
- 전제 조건:
download파라미터가 정상 작동하려면 DRM 다운로드 콜백 설정이 선행되어야 합니다. (상세 가이드: 콜백 연동 - DRM 다운로드 콜백) - 폴더 경로 설정:
/기호를 사용하여 계층 구조를 가진 하위 폴더를 지정할 수 있습니다. (예:folder1/folder2/folder3) - 데이터 인코딩: 폴더 이름에 한글, 특수문자, 공백이 포함된 경우, 반드시 해당 값을 UTF-8 URL 인코딩(URL Encoding) 처리하여 전달해야 합니다.
- R링크 활성화: R링크는 기본적으로 비활성화되어 있습니다. 해당 기능을 활성화하려면 영업 담당자(AM, biz@catenoid.net) 또는 기술 지원팀(PE, tech_support@catenoid.net)으로 문의해 주세요.
플레이어
| 파라미터 | 타입 | 지원 플레이어 | 설명 |
|---|---|---|---|
player_version (pv) | string | Desktop | 플레이어 지정
|
force_exclusive_player | null | v3e, v3h | 비암호화 콘텐츠 재생 시에도 PC용 보안 플레이어 적용 |
force_independant_player | boolean | v3 | 보안 플레이어 강제 적용 |
컨트롤바
| 파라미터 | 타입 | 지원 플레이어 | 설명 |
|---|---|---|---|
controls_activation | string | v3, v4, v5 | 컨트롤바 활성화 정책
|
show_controls_paused | boolean | v4 | 일시정지 상태에서 컨트롤바 유지 여부 (기본값: false) |
set_controlbar_progress_only | boolean | v4, v5 | 프로그레스 바(Progress Bar)만 노출 |
transparent_controlbar_layer | boolean | v4, v5 | 컨트롤바 배경 투명화 |
hide_header_display | boolean | v4, v5 | 헤더 영역 숨김 |
오버레이 / 포스터
| 파라미터 | 타입 | 지원 플레이어 | 설명 |
|---|---|---|---|
overlay_button_position | string | v4 | 오버레이 버튼 위치
|
show_poster_ended | boolean | v4 | 재생 종료 후 포스터 노출 여부 (기본값: false) |
enable_poster | boolean | v4, v5 | 포스터 활성화 여부 |
enable_spinner_activation | boolean | v4, v5 | 로딩 아이콘 활성화 여부 |
섬네일 / 타임 디스플레이
| 파라미터 | 타입 | 지원 플레이어 | 설명 |
|---|---|---|---|
enable_thumbnail | boolean | v4, v5 | 프로그레스 바 탐색 시 섬네일 미리보기 활성화 |
enable_mouse_time_display | boolean | v5 | 마우스 오버 시 타임 디스플레이 노출 |
탐색(Seek) / 자동 재생
| 파라미터 | 타입 | 지원 플레이어 | 설명 |
|---|---|---|---|
autoplay_after_seek | string | v4, v5 | 재생 시점 이동(Seek) 후 재생 정책
|
disable_autoplay | boolean | v4, v5 | 자동 재생 가능 상황에서도 해당 기능 비활성화 |
play_at | number | v3 | 이어보기 시점 설정 |
버퍼링 / 스트리밍
| 파라미터 | 타입 | 지원 플레이어 | 설명 |
|---|---|---|---|
buffer | integer | v3e, v3h | 버퍼링 배수 설정 (2~10배) |
frag_load_paused | boolean | v4, v5 | 일시정지 상태에서 HLS Fragment 로딩 여부 |
force_custom_header | boolean | v4, v5 | HLS 동시 접속 체크 헤더(X-Kollus-SessionId) 강제 추가 |
force_use_credentials | boolean | v4, v5 | HLS XHR 요청 시 withCredentials 강제 적용 |
화면 제어
| 파라미터 | 타입 | 지원 플레이어 | 설명 |
|---|---|---|---|
force_landscape_fullscreen | boolean | v4, v5 | 모바일 전체 화면 재생 시 화면 방향을 가로로 고정 |
force_rotate_fullscreen | boolean | v4, v5 | 모바일 디바이스 가로 회전 시 전체 화면 모드 강제 실행 |
enable_pip | boolean | v3, v4, v5 | PIP(Picture-in-Picture) 모드 허용 |
pointcolor | number | v4, v5 | UI 포인트 색상 변경 (HEX, # 제외) |
is_vr | boolean | v4, v5 | VR 플레이어 재생 |
is_dvr | boolean | v4, v5 | DVR Timeshift 활성화 |
입력 / 접근성
| 파라미터 | 타입 | 지원 플레이어 | 설명 |
|---|---|---|---|
enable_hotkey | boolean | v4, v5 | 단축키 활성화 |
enable_volume_scroll | boolean | v4, v5 | 마우스 휠 볼륨 조절 활성화 |
enable_context_menu | boolean | v3, v4, v5 | 마우스 우클릭 컨텍스트 메뉴 사용 허용 |
enable_accessibility | boolean | v3, v4, v5 | 웹 접근성 기능 활성화 |
enable_initialize_focus | boolean | v3, v4 | 플레이어 로드 시 포커스 적용 (기본값: true) |
iOS 전용 옵션
| 파라미터 | 타입 | 지원 플레이어 | 설명 |
|---|---|---|---|
ios_player_type | string | iOS | iOS 디코더 타입 (App Player for iOS 버전 2.2.14 이상 적용 필수)
|
mobile_return_url | string | iOS | 뒤로가기/종료 시 이동할 URL (Safari 브라우저 실행) |
개발 / 디버깅
| 파라미터 | 타입 | 지원 플레이어 | 설명 |
|---|---|---|---|
debug_mode | boolean | v3, v4, v5 | 브라우저 콘솔에 디버그 로그 출력 |
debug_mode2 | boolean | v4, v5 | 상세 이벤트 로그 및 데이터 상태 출력 |
agent_mode | boolean | v3 | Kollus Agent 체크 실행 여부 |
agent_url | string | v3 | Kollus Agent URL 설정 (debug_mode=true 설정 시 작동) |
loadcheck | integer | v3 | 0: 플레이 콜백에서 메시지 사용 |
media_key_src | string | v3 | 미디어 키 직접 지정 |
media_url | string | v3 | 재생 URL 직접 지정 |
기타
| 파라미터 | 타입 | 지원 플레이어 | 설명 |
|---|---|---|---|
uservalue{0~99} | mixed | All | 고객사 정의 값 (uservalue0~uservalue99)플레이, DRM, LMS 콜백 등 클라이언트 정보 전송 시 함께 전달됩니다. |
사용 예제
ℹ️식별 키(Key) 정보
식별 키 정보는 아래 문서를 참고하세요.
시청 경험 최적화 (재생 제어)
자동 재생 및 초기 음소거 설정
브라우저의 자동 재생 차단 정책을 우회하여 시청 진입을 자동화하는 옵션 조합입니다.
https://v.kr.kollus.com/{MEDIA_CONTENT_KEY}?autoplay&mute
10초 지점부터 즉시 재생
이어보기 팝업 노출 없이 지정된 시점부터 즉시 재생을 시작합니다.
https://v.kr.kollus.com/{MEDIA_CONTENT_KEY}?s=10
화질(프로파일) 지정 및 제목 변경
특정 화질을 선택하거나 플레이어에 표시될 제목을 지정합니다. title 값에 한글이나 공백이 포함될 경우 반드시 UTF-8 URL 인코딩 처리를 수행해야 합니다.
https://v.kr.kollus.com/{MEDIA_CONTENT_KEY}?pf={ENCODING_PROFILE_KEY}&title={TITLE}
UI 제어
플레이어 지정 및 디버깅 로그 활성화
특정 플레이어 환경을 테스트하거나 브라우저 개발자 도구(Console)에서 로그를 확인할 때 활용합니다.
https://v.kr.kollus.com/{MEDIA_CONTENT_KEY}?player_version=v4&debug_mode=true
모바일 전체 화면 전환 시 가로 방향 고정
모바일 시청자가 전체 화면 버튼을 눌렀을 때, 디바이스 방향에 관계없이 화면 방향을 가로로 전환합니다.
https://v.kr.kollus.com/{MEDIA_CONTENT_KEY}?force_landscape_fullscreen=true
컨트롤바 고정 노출 및 포인트 색상 변경
사용자 조작이 없어도 컨트롤바를 항상 노출하며, 브랜드 테마에 맞춰 포인트 색상을 적용합니다.
https://v.kr.kollus.com/{MEDIA_CONTENT_KEY}?controls_activation=always&pointcolor=FF5500
다운로드
다운로드 모드 실행 및 폴더 경로 지정
콘텐츠를 저장할 하위 폴더 경로를 지정합니다. 특수문자나 한글이 포함된 경로는 반드시 UTF-8 URL 인코딩 처리를 수행해야 합니다.
https://v.kr.kollus.com/{MEDIA_CONTENT_KEY}?download&mobile_folder_download=movie/action