플레이어 호출 옵션 (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 인코딩 처리하여 전달해야 합니다.

Kollus 플레이어 구분

Kollus 플레이어에 대한 상세 설명은 Kollus 플레이어 종류 문서를 참고하세요.

표기	플레이어 이름	특징
v3e	App Player for Windows	설치형 에이전트 방식 플레이어
v3h	HTML5 Player for PC	설치형 HTML5 에이전트 방식 플레이어
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 전용 앱 플레이어

전체 옵션

재생

파라미터	타입	설명	대상 플레이어
`autoplay (a)`	`null`	자동 재생 설정 (모바일 환경은 기본 활성화)	전체
`mute`	`null`	음소거 상태로 재생 시작	전체
`t`	`integer`	지정 시점(sec)부터 재생 및 이어보기 팝업 노출	전체
`s`	`integer`	지정 시점(sec)부터 재생 및 이어보기 팝업 없음	전체
`title`	`string`	콘텐츠 제목 강제 지정	전체
`pf`	`string`	인코딩 프로파일(화질) 강제 지정	전체

참고

재생 옵션 예외: t 또는 s 값이 영상의 시작/종료 10초 이내인 경우, 시스템 안정성을 위해 영상의 처음(0초)부터 재생됩니다.
브라우저/플랫폼 자동 재생 정책: 최신 브라우저는 사운드가 포함된 영상의 자동 재생을 기본 차단합니다. 상세 내용은 아래 '브라우저/플랫폼별 자동 재생 정책'을 참고하세요.

브라우저/플랫폼별 자동 재생 정책

브라우저 및 플랫폼	사운드 미포함 비디오	사운드 포함 비디오	비고
Chrome	자동 재생 허용	기본 차단	사용자의 미디어 참여 지수(MEI)가 높거나 이전 클릭 기록이 있는 경우에만 예외적으로 자동 재생 허용
Edge	자동 재생 허용	기본 차단	사용자가 브라우저 설정에서 자동 재생을 '허용'으로 변경한 경우 자동 재생 허용 기업 환경에서 관리자가 그룹 정책(AutoplayAllowed)을 '허용'으로 배포한 경우 자동 재생 허용
Safari (macOS)	자동 재생 허용	기본 차단	사용자가 Safari 설정에서 웹사이트별로 자동 재생 허용 여부를 개별 변경 가능
iOS (iPhone/iPad)	자동 재생 허용 (`playsinline` 필수)	기본 차단	사용자의 직접적인 화면 터치(제스처) 이후에만 스크립트를 통한 재생 허용
Firefox	자동 재생 허용	기본 차단	사용자가 브라우저 설정에서 자동 재생 차단 및 허용 수준을 변경 가능

참조 자료

권장 구현 가이드라인

사운드가 포함된 비디오는 음소거 상태로 자동 재생을 시작하는 것을 권장합니다. 이후 사용자가 직접 오디오를 활성화할 수 있도록 음소거 해제 버튼을 함께 제공하세요.

다운로드

파라미터	타입	설명	대상 플레이어
`download`	`null`	콘텐츠 다운로드 기능 활성화	모바일, v3e, v3h
`mobile_folder_download`	`string`	모바일 다운로드 폴더 경로 지정	모바일
`pc_folder_download`	`string`	PC 다운로드 폴더 경로 지정	v3e, v3h
`filename`	`string`	R링크, SR링크 사용 시 저장될 파일 이름 지정	전체

참고

전제 조건: download 파라미터가 정상 작동하려면 DRM 다운로드 콜백 설정이 선행되어야 합니다. (참고: 콜백 연동 - DRM 다운로드 콜백)
폴더 경로 설정: / 기호를 사용하여 하위 폴더를 지정할 수 있습니다.
- 예: folder1/folder2/folder3
인코딩: 폴더 이름에 한글, 특수문자, 공백이 포함된 경우, 반드시 해당 값을 UTF-8 URL 인코딩 처리하여 전달해야 합니다.
R링크 활성화 안내: R링크는 기본적으로 비활성화되어 있습니다. 해당 기능을 활성화하려면 기술 지원팀(tech_support@kollus.com) 또는 영업 담당자(AM)에게 문의해 주세요.

플레이어

파라미터	타입	설명	대상 플레이어
`player_version (pv)`	`string`	플레이어 지정 `v3h`: HTML5 Player for PC `v3e`: App Player for Windows `v4`: HTML5 Player for All `v5`: Web Player `미지정`: 재생 환경에 맞춰 자동 적용	PC
`force_exclusive_player`	`null`	비암호화 콘텐츠 재생 시에도 PC용 Kollus 보안 플레이어 적용	v3e, v3h
`force_independent_player`	`boolean`	Kollus 보안 플레이어 강제 적용	v3

컨트롤바

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

오버레이 / 포스터

파라미터	타입	설명	대상 플레이어
`overlay_button_position`	`string`	오버레이 버튼 위치 `TR`: 우측 상단 (Top Right) `TL`: 좌측 상단 (Top Left) `BR`: 우측 하단 (Bottom Right) `BL`: 좌측 하단 (Bottom Left) `미지정`: 중앙 정렬	v4
`show_poster_ended`	`boolean`	재생 종료 후 포스터 노출 여부 (기본값: `false`)	v4
`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`	재생 시점 이동(Seek) 후 재생 정책 `auto`: 재생 중 이동 시 자동 재생, 일시정지 중 이동 시 정지 유지 `play`: 이동 후 즉시 재생 `pause`: 이동 후 정지	v4, v5
`disable_autoplay`	`boolean`	자동 재생 가능 상황에서도 해당 기능 비활성화	v4, v5
`play_at`	`number`	이어보기 시점 설정	v3

버퍼링 / 스트리밍

파라미터	타입	설명	대상 플레이어
`buffer`	`integer`	버퍼링 배수 설정 (2~10배)	v3e, v3h
`frag_load_paused`	`boolean`	일시정지 상태에서 HLS Fragment 로딩 여부	v4, v5
`force_custom_header`	`boolean`	HLS 동시 접속 확인 헤더(`X-Kollus-SessionId`) 강제 추가	v4, v5
`force_use_credentials`	`boolean`	HLS XHR 요청 시 `withCredentials` 강제 적용	v4, v5

화면 제어

파라미터	타입	설명	대상 플레이어
`force_landscape_fullscreen`	`boolean`	모바일 전체 화면 재생 시 화면 방향을 가로로 고정	v4, v5
`force_rotate_fullscreen`	`boolean`	모바일 디바이스 가로 회전 시 전체 화면 모드 강제 실행	v4, v5
`enable_pip`	`boolean`	PIP(Picture-in-Picture) 모드 허용	v3, v4, v5
`pointcolor`	`number`	UI 포인트 색상 변경 (HEX, # 제외)	v4, v5
`is_vr`	`boolean`	VR 플레이어 재생	v4, v5
`is_dvr`	`boolean`	DVR 타임시프트 활성화	v4, v5

입력 / 접근성

파라미터	타입	설명	대상 플레이어
`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`	플레이어 로드 시 포커스 적용 (기본값: `true`)	v3, v4

iOS 전용 옵션

파라미터	타입	설명
`ios_player_type`	`string`	iOS 디코더 타입 (App Player for iOS 버전 2.2.14 이상 적용 필수) `native`: Native 디코더 `hw`: 하드웨어 디코더 `sw`: 소프트웨어 디코더
`mobile_return_url`	`string`	뒤로가기/종료 시 이동할 URL (Safari 브라우저 실행)

개발 / 디버깅

파라미터	타입	설명	대상 플레이어
`debug_mode`	`boolean`	브라우저 콘솔에 디버그 로그 출력	v3, v4, v5
`debug_mode2`	`boolean`	상세 이벤트 로그 및 데이터 상태 출력	v4, v5
`agent_mode`	`boolean`	KollusAgent 검사 실행 여부	v3
`agent_url`	`string`	KollusAgent URL 설정 (`debug_mode=true` 설정 시 작동)	v3
`loadcheck`	`integer`	`0`: 플레이 콜백에서 메시지 사용	v3
`media_key_src`	`string`	미디어 키 직접 지정	v3
`media_url`	`string`	재생 URL 직접 지정	v3

기타

파라미터	타입	설명	대상 플레이어
`uservalue{0~99}`	`mixed`	커스텀 변수 (`uservalue0`~`uservalue99`) 플레이, DRM, LMS 콜백 등 클라이언트 정보 전송 시 함께 전달됩니다.	전체

사용 예제

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

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

브라우저의 자동 재생 차단 정책을 우회하여 시청 진입을 자동화하는 옵션 조합입니다.

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

Query String 형식​

Kollus 플레이어 구분​

전체 옵션​

재생​

브라우저/플랫폼별 자동 재생 정책​

참조 자료​

다운로드​

플레이어​

컨트롤바​

오버레이 / 포스터​

섬네일 / 타임 디스플레이​

탐색(Seek) / 자동 재생​

버퍼링 / 스트리밍​

화면 제어​

입력 / 접근성​

iOS 전용 옵션​

개발 / 디버깅​

기타​

사용 예제​

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

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

10초 지점부터 즉시 재생​

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

UI 제어​

플레이어 지정 및 디버깅 로그 활성화​

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

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

다운로드​

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

Query String 형식

Kollus 플레이어 구분

전체 옵션

재생

브라우저/플랫폼별 자동 재생 정책

참조 자료

다운로드

플레이어

컨트롤바

오버레이 / 포스터

섬네일 / 타임 디스플레이

탐색(Seek) / 자동 재생

버퍼링 / 스트리밍

화면 제어

입력 / 접근성

iOS 전용 옵션

개발 / 디버깅

기타

사용 예제

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

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

10초 지점부터 즉시 재생

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

UI 제어

플레이어 지정 및 디버깅 로그 활성화

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

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

다운로드

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