본문으로 건너뛰기

플레이어 호출 옵션 (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)
  • 인코딩: 파라미터 값에 한글, 특수문자, 공백이 포함된 경우, 반드시 해당 값을 URL 인코딩(URL Encoding) 처리하여 전달해야 합니다.

Kollus 플레이어 구분​

표기플레이어 이름특징
v3eApp Player for Windows설치형 Agent 방식 플레이어
v3hHtml5 Player for PC설치형 HTML5 Agent 방식 플레이어
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)nullAll자동 재생 설정 (모바일 환경은 기본 활성화)
mutenullAll음소거 상태로 재생 시작
tintegerAll지정 시점(초)부터 재생 및 이어보기 팝업 노출
sintegerAll지정 시점(초)부터 재생 및 이어보기 팝업 없음
titlestringAll콘텐츠 제목 강제 지정
pfstringAll인코딩 프로파일(화질) 강제 지정
ℹ️참고
  • 재생 옵션 예외: t 또는 s 값이 영상의 시작/종료 10초 이내인 경우, 시스템 안정성을 위해 영상의 처음(0초)부터 재생됩니다.
  • 브라우저 자동 재생 정책: Chrome 및 최신 브라우저는 음성이 포함된 영상의 자동 재생이 기본 차단합니다. 상세 내용은 Chrome의 자동 재생 정책 문서를 참고하세요.

다운로드​

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

플레이어​

파라미터타입지원 플레이어설명
player_version (pv)stringDesktop플레이어 지정
  • v3h: Html5 Player for PC
  • v3e: App Player for Windows
  • v4: Html5 Player for All
  • v5: Web Player
  • 미지정: 재생 환경에 맞춰 자동 적용
force_exclusive_playernullv3e, v3h비암호화 콘텐츠 재생 시에도 PC용 보안 플레이어 적용
force_independant_playerbooleanv3보안 플레이어 강제 적용

컨트롤바​

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

오버레이 / 포스터​

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

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

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

탐색(Seek) / 자동 재생​

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

버퍼링 / 스트리밍​

파라미터타입지원 플레이어설명
bufferintegerv3e, v3h버퍼링 배수 설정 (2~10배)
frag_load_pausedbooleanv4, v5일시정지 상태에서 HLS Fragment 로딩 여부
force_custom_headerbooleanv4, v5HLS 동시 접속 체크 헤더(X-Kollus-SessionId) 강제 추가
force_use_credentialsbooleanv4, v5HLS XHR 요청 시 withCredentials 강제 적용

화면 제어​

파라미터타입지원 플레이어설명
force_landscape_fullscreenbooleanv4, v5모바일 전체 화면 재생 시 화면 방향을 가로로 고정
force_rotate_fullscreenbooleanv4, v5모바일 기기 가로 회전 시 전체 화면 모드 강제 실행
enable_pipbooleanv3, v4, v5PIP(Picture-in-Picture) 모드 허용
pointcolornumberv4, v5UI 포인트 색상 변경 (HEX, # 제외)
is_vrbooleanv4, v5VR 플레이어 재생
is_dvrbooleanv4, v5DVR Timeshift 활성화

입력 / 접근성​

파라미터타입지원 플레이어설명
enable_hotkeybooleanv4, v5단축키 활성화
enable_volume_scrollbooleanv4, v5마우스 휠 볼륨 조절 활성화
enable_context_menubooleanv3, v4, v5마우스 우클릭 컨텍스트 메뉴 사용 허용
enable_accessibilitybooleanv3, v4, v5웹 접근성 기능 활성화
enable_initialize_focusbooleanv3, v4플레이어 로드 시 포커스 적용 (기본값: true)

iOS 전용 옵션​

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

개발 / 디버깅​

파라미터타입지원 플레이어설명
debug_modebooleanv3, v4, v5브라우저 콘솔에 디버그 로그 출력
debug_mode2booleanv4, v5상세 이벤트 로그 및 데이터 상태 출력
agent_modebooleanv3Kollus Agent 체크 실행 여부
agent_urlstringv3Kollus Agent URL 설정 (debug_mode=true 설정 시 작동)
loadcheckintegerv30: 플레이 콜백에서 메시지 사용
media_key_srcstringv3미디어 키 직접 지정
media_urlstringv3재생 URL 직접 지정

기타​

파라미터타입지원 플레이어설명
uservalue{0~99}mixedAll고객사 정의 값 (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 값에 한글이나 공백이 포함될 경우 반드시 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

다운로드​

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

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

https://v.kr.kollus.com/{MEDIA_CONTENT_KEY}?download&mobile_folder_download=movie/action