플레이어 호출 옵션 (Query String)

이 문서는 재생 URL 뒤에 Query String을 추가하여 플레이어의 동작을 세밀하게 제어하는 방법을 설명합니다.

---

Query String 형식

재생 URL에 파라미터를 추가하는 규칙은 다음과 같습니다.

https://v.kr.kollus.com/{MEDIA_CONTENT_KEY}?key=value&key2=value2

• 구분자: URL 끝에 ?를 붙입니다. 여러 옵션을 연결할 때는 &를 사용합니다.
• 플래그 형식: 별도의 값(value)이 필요 없는 옵션은 키(key)만 입력합니다.(예: ?autoplay&mute)
• 인코딩: 값에 한글, 특수문자, 공백이 포함된 경우 반드시 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	비암호화 콘텐츠 전용 비설치형(No-installation required) HTML5 Player
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	integer	all	설정한 시점(단위: 초)부터 재생 및 이어보기 팝업 없음
title	string	all	콘텐츠 제목 강제 지정
pf	string	all	재생 프로파일 강제 지정

ℹ️참고

• 재생 구간 예외 처리: t 또는 s 값을 영상 시작 후 10초 이내 또는 종료 전 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)
• 데이터 포맷: 폴더 이름에 한글, 공백, 특수문자가 포함될 경우, 반드시 해당 값을 URL 인코딩하여 전달해야 합니다.
• R링크 활성화: R링크는 기본적으로 비활성화되어 있습니다.
  해당 기능을 활성화하려면 Kollus 영업 담당자(AM, biz@catenoid.net) 또는 기술 지원팀(PE, tech_support@catenoid.net)으로 문의해 주세요.

플레이어

파라미터	타입	지원 플레이어	설명
player_version (pv)	string	desktop	플레이어 지정(미지정 시 환경에 맞게 자동 지정) v3h: Html5 Player for PC v3e: App Player for Windows v4: Html5 Player for All (비보안) v5: Web Player
force_exclusive_player	null	v3e, v3h	비암호화 콘텐츠도 PC 전용 플레이어 사용 강제
force_independant_player	boolean	v3	전용 플레이어 강제 실행

컨트롤바

파라미터	타입	지원 플레이어	설명
controls_activation	string	v3, v4, v5	컨트롤바 활성화 정책 auto: inactive_time에 따라 자동 표시/숨김 전환 always: 항상 표시 none: 항상 숨김
show_controls_paused	boolean	v4	일시정지 시 컨트롤바 유지 여부(기본값: false)
set_controlbar_progress_only	boolean	v4, v5	프로그레스바만 표시
transparent_controlbar_layer	boolean	v4, v5	컨트롤바 배경 투명화
hide_header_display	boolean	v4, v5	헤더 숨김

오버레이 / 포스터

파라미터	타입	지원 플레이어	설명
overlay_button_position	string	v4	오버레이 버튼 위치 TR: Top Right(오른쪽 상단) TL: Top Left(왼쪽 상단) BR: Bottom Right(오른쪽 하단) BL: Bottom Left(왼쪽 하단) 미지정: 가운데 정렬
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	재생 시점 이동 후 재생 정책 auto: 재생 중 이동 시 자동 재생, 일시정지 상태에서 이동 시 자동 재생 안 함 play: 무조건 자동 재생 pause: 무조건 자동 재생 안 함
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	포인트 색상 변경(HEX, # 제외)
is_vr	boolean	v4, v5	VR Player 재생
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 디코더 타입 ⚠️ ios_player_type은 App Player for iOS 2.2.14 이상에서 동작합니다. native: 네이티브 디코더 hw: 하드웨어 디코더 sw: 소프트웨어 디코더
mobile_return_url	string	iOS	뒤로가기/종료 시 이동할 URL(Safari로 열림)

개발 / 디버깅

파라미터	타입	지원 플레이어	설명
debug_mode	boolean	v3, v4, v5	디버깅 콘솔 출력
debug_mode2	boolean	v4, v5	디버깅 모드 및 이벤트 로그 출력
agent_mode	boolean	v3	Kollus Agent Check 실행 여부
agent_url	string	v3	Kollus Agent URL 설정(debug_mode=true 설정 시에만 동작)
loadcheck	integer	v3	0: 플레이 콜백에서 메시지 사용
media_key_src	string	v3	미디어 키 직접 지정
media_url	string	v3	미디어 콘텐츠 URL 직접 지정

기타

파라미터	타입	지원 플레이어	설명
{uservalue0~99}	mixed	all	고객사 정의 값(uservalue0~uservalue99) 플레이, DRM, LMS 콜백 등 클라이언트 정보 전송 시 함께 전달됩니다.

---

사용 예제

시청 경험 최적화 (재생 제어)

자동 재생 및 초기 음소거 설정

브라우저의 자동 재생 차단 정책을 우회하기 위한 가장 권장되는 조합입니다.

https://v.kr.kollus.com/vnCVPVyV?autoplay&mute

10초부터 재생

이어보기 팝업(Resume Prompt) 없이 즉시 지정된 시간부터 시작합니다.

https://v.kr.kollus.com/vnCVPVyV?s=10

화질(프로파일) 지정 및 제목 변경

title 값에 한글이나 공백이 포함될 경우 반드시 URL 인코딩이 필요합니다.

https://v.kr.kollus.com/vnCVPVyV?pf=mixnut-pc-high1&title={제목}

UI 제어

플레이어 강제 지정 및 디버깅 로그 출력

특정 플레이어 환경을 테스트하거나 개발자 도구(Console)에서 로그를 확인할 때 사용합니다.

https://v.kr.kollus.com/vnCVPVyV?player_version=v4&debug_mode=true

모바일 전체 화면 전환 시 가로 방향 고정

모바일 사용자가 전체 화면 버튼을 눌렀을 때 기기 방향에 상관없이 가로로 자동 전환합니다.

https://v.kr.kollus.com/vnCVPVyV?force_landscape_fullscreen=true

컨트롤바 고정 노출 및 포인트 색상 변경

사용자 조작이 없어도 컨트롤바를 항상 표시하며, 브랜드 테마에 맞춰 포인트 색상을 적용합니다.

https://v.kr.kollus.com/vnCVPVyV?controls_activation=always&pointcolor=FF5500

다운로드

다운로드 모드 실행 및 폴더 경로 지정

콘텐츠를 저장할 하위 폴더 경로를 지정합니다. 특수문자나 한글 경로는 반드시 인코딩해야 합니다.

https://v.kr.kollus.com/vnCVPVyV?download&mobile_folder_download=movie/action