본문으로 건너뛰기

플레이어 호출 옵션 (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 플레이어 구분​

표기플레이어 이름특징
v3eApp Player for Windows설치형 에이전트 방식 플레이어
v3hHTML5 Player for PC설치형 HTML5 에이전트 방식 플레이어
v3HTML5 Player for PC (Hybrid)Microsoft Edge 또는 Chrome 45 이상에서 암호화 콘텐츠 재생 시 적용되는 하이브리드 HTML5 플레이어
v4HTML5 Player for All비암호화 콘텐츠 전용 비설치형 HTML5 플레이어
v5Web Player설치형과 비설치형의 장점을 결합한 차세대 통합 웹 플레이어
iOSApp Player for iOSiOS 전용 앱 플레이어
AndroidApp Player for AndroidAndroid 전용 앱 플레이어
플레이어 안내

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

전체 옵션​

재생​

파라미터타입설명대상 플레이어
autoplay (a)null자동 재생 설정 (모바일 환경은 기본 활성화)전체
mutenull음소거 상태로 재생 시작전체
tinteger지정 시점(sec)부터 재생 및 이어보기 팝업 노출전체
sinteger지정 시점(sec)부터 재생 및 이어보기 팝업 없음전체
titlestring콘텐츠 제목 강제 지정전체
pfstring인코딩 프로파일(화질) 강제 지정전체
주의
  • 재생 옵션 예외: t 또는 s 값이 영상의 시작/종료 10초 이내인 경우, 시스템 안정성을 위해 영상의 처음(0초)부터 재생됩니다.
  • 브라우저/플랫폼 자동 재생 정책: 최신 브라우저는 사운드가 포함된 영상의 자동 재생을 기본 차단합니다. 상세 내용은 아래 '브라우저/플랫폼별 자동 재생 정책'을 참고하세요.
브라우저/플랫폼별 자동 재생 정책

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

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

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

다운로드​

파라미터타입설명대상 플레이어
downloadnull콘텐츠 다운로드 기능 활성화모바일, v3e, v3h
mobile_folder_downloadstring모바일 다운로드 폴더 경로 지정모바일
pc_folder_downloadstringPC 다운로드 폴더 경로 지정v3e, v3h
filenamestringR링크, SR링크 사용 시 저장될 파일 이름 지정전체
참고
  • 전제 조건: download 파라미터가 정상 작동하려면 DRM 다운로드 콜백 설정이 선행되어야 합니다.
  • 폴더 경로 설정: / 기호를 사용하여 하위 폴더를 지정할 수 있습니다.
    • 예: folder1/folder2/folder3
  • 인코딩: 폴더 이름에 한글, 특수문자, 공백이 포함된 경우, 반드시 해당 값을 UTF-8 URL 인코딩 처리하여 전달해야 합니다.
  • R링크 활성화: R링크는 기본적으로 비활성화되어 있습니다. 해당 기능을 활성화하려면 영업 담당자(AM, biz@catenoid.net) 또는 기술 지원팀(PE, tech_support@catenoid.net)으로 문의해 주세요.

플레이어​

파라미터타입설명대상 플레이어
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_playernull비암호화 콘텐츠 재생 시에도 PC용 Kollus 보안 플레이어 적용v3e, v3h
force_independent_playerbooleanKollus 보안 플레이어 강제 적용v3

컨트롤바​

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

오버레이 / 포스터​

파라미터타입설명대상 플레이어
overlay_button_positionstring오버레이 버튼 위치
  • TR: 우측 상단 (Top Right)
  • TL: 좌측 상단 (Top Left)
  • BR: 우측 하단 (Bottom Right)
  • BL: 좌측 하단 (Bottom Left)
  • 미지정: 중앙 정렬
v4
show_poster_endedboolean재생 종료 후 포스터 노출 여부 (기본값: false)v4
enable_posterboolean포스터 활성화 여부v4, v5
enable_spinner_activationboolean로딩 아이콘 활성화 여부v4, v5

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

파라미터타입설명대상 플레이어
enable_thumbnailboolean프로그레스 바 탐색 시 섬네일 미리보기 활성화v4, v5
enable_mouse_time_displayboolean마우스 오버 시 타임 디스플레이 노출v5

탐색(Seek) / 자동 재생​

파라미터타입설명대상 플레이어
autoplay_after_seekstring재생 시점 이동(Seek) 후 재생 정책
  • auto: 재생 중 이동 시 자동 재생, 일시정지 중 이동 시 정지 유지
  • play: 이동 후 즉시 재생
  • pause: 이동 후 정지
v4, v5
disable_autoplayboolean자동 재생 가능 상황에서도 해당 기능 비활성화v4, v5
play_atnumber이어보기 시점 설정v3

버퍼링 / 스트리밍​

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

화면 제어​

파라미터타입설명대상 플레이어
force_landscape_fullscreenboolean모바일 전체 화면 재생 시 화면 방향을 가로로 고정v4, v5
force_rotate_fullscreenboolean모바일 디바이스 가로 회전 시 전체 화면 모드 강제 실행v4, v5
enable_pipbooleanPIP(Picture-in-Picture) 모드 허용v3, v4, v5
pointcolornumberUI 포인트 색상 변경 (HEX, # 제외)v4, v5
is_vrbooleanVR 플레이어 재생v4, v5
is_dvrbooleanDVR 타임시프트 활성화v4, v5

입력 / 접근성​

파라미터타입설명대상 플레이어
enable_hotkeyboolean단축키 활성화v4, v5
enable_volume_scrollboolean마우스 휠 볼륨 조절 활성화v4, v5
enable_context_menuboolean마우스 우클릭 컨텍스트 메뉴 사용 허용v3, v4, v5
enable_accessibilityboolean웹 접근성 기능 활성화v3, v4, v5
enable_initialize_focusboolean플레이어 로드 시 포커스 적용 (기본값: true)v3, v4

iOS 전용 옵션​

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

개발 / 디버깅​

파라미터타입설명대상 플레이어
debug_modeboolean브라우저 콘솔에 디버그 로그 출력v3, v4, v5
debug_mode2boolean상세 이벤트 로그 및 데이터 상태 출력v4, v5
agent_modebooleanKollusAgent 검사 실행 여부v3
agent_urlstringKollusAgent URL 설정 (debug_mode=true 설정 시 작동)v3
loadcheckinteger0: 플레이 콜백에서 메시지 사용v3
media_key_srcstring미디어 키 직접 지정v3
media_urlstring재생 URL 직접 지정v3

기타​

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

사용 예제​

관련 정보

키(Key/ID) 정보는 아래 문서를 참고하세요.

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

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

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

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