플로팅 플레이어

자주 쓰는 조합

아래 세 가지를 조합해 구성합니다 — 플로팅 모드 · 띄울 방송 · UI 레이아웃.
대표적인 조합부터 확인하고, 각 항목의 선택 기준은 아래 섹션에서 이어집니다.

하고 싶은 것	설정
상세페이지에서 스크롤로 지나쳐도 계속 보이게	`type: 'scroll'` + 컨트롤형
라이브 링크를 공유해 바로 시청하게	`setInit` + `type: 'basic'` + 컨트롤형
홈에서 "지금 하는 라이브"를 알리기	`setOnAirInit` + `type: 'basic'` + 배지형
특정 영역 안에서만 움직이게	`type: 'basic'` + `restrictionArea`

플로팅 모드 선택

setFloatingType()의 type 값으로 모드를 선택합니다.

비교 항목	📌 기본 플로팅 `basic`	📜 스크롤 플로팅 `scroll`
등장 시점	페이지 로드 시 바로 플로팅 플레이어로 표시	임베드된 플레이어를 지나 스크롤할 때 플로팅으로 전환
전제 조건	일반 플레이어 영역이 없어도 됨	페이지에 일반 플레이어가 임베드되어 있어야 자연스러움
닫기 버튼	사라진 뒤 재접속 시 다시 노출	사라진 뒤 원래 위치로 스크롤하면 다시 생성
확대 버튼	기본 플레이어 링크로 이동	플레이어 위치(최상단)로 스크롤
위치 이동(드래그)	가능 — 드래그 후 가까운 모서리로 자동 정렬	불가 — 지정한 위치에 고정
추천 상황	플로팅을 단독으로 사용하거나, 라이브 링크를 공유해 바로 시청하게 할 때	상세페이지에 플레이어가 있고, 스크롤로 지나쳐도 시청을 유지하고 싶을 때

📌 기본 플로팅 `type: 'basic'`

페이지 로드 시 바로 플로팅 플레이어 형태로 나타납니다.

닫기 버튼: 플로팅 플레이어가 사라지며, 재접속 시 다시 노출됩니다.
확대 버튼: 기본 플레이어 링크로 리다이렉트됩니다.

이런 상황에 적합

별도 일반 플레이어 영역 없이 플로팅만 단독으로 사용할 때
라이브 링크를 공유해 바로 플로팅으로 시청하게 할 때

📜 스크롤 플로팅 `type: 'scroll'`

플레이어가 화면에서 보이지 않을 때 스크롤 이벤트에 따라 플로팅 형태로 전환됩니다.

닫기 버튼: UI가 사라지지만 원래 위치로 스크롤 시 다시 생성됩니다.
확대 버튼: 최상단 위치로 스크롤을 올려줍니다.

이런 상황에 적합

자사몰 페이지에 일반 플레이어가 이미 임베드되어 있을 때
사용자가 스크롤해 플레이어를 지나쳐도 시청을 유지시키고 싶을 때

JavaScript — 기본 플로팅

window.SauceLiveLib.setInit({ broadcastId: '라이브ID를 입력해주세요' });
window.SauceLiveLib.setFloatingType({ type: 'basic' });
window.SauceLiveLib.load();

JavaScript — 스크롤 플로팅

window.SauceLiveLib.setInit({ broadcastId: '라이브ID를 입력해주세요' });
window.SauceLiveLib.setFloatingType({ type: 'scroll' });
window.SauceLiveLib.load();

띄울 방송 정하기

플레이어를 초기화하는 함수는 두 가지이고, 둘 중 하나만 호출합니다.
띄울 라이브가 정해져 있으면 setInit(), "지금 진행 중인 라이브"를 자동으로 띄우려면 setOnAirInit()을 사용합니다.

비교 항목	🎯 라이브 ID 지정 `setInit`	🔄 진행 중인 라이브 자동 선택 `setOnAirInit`
필요한 값	`broadcastId` (라이브 ID)	`partnerId` (파트너 ID)
어떤 방송	지정한 그 라이브	진행 중인 라이브 중 가장 최근에 시작한 라이브
방송 결정 시점	호출하는 순간 확정	`load()` 시점에 자동 조회 후 확정
진행 중인 라이브가 없으면	해당 없음	아무것도 표시하지 않음 (오류 아님)
페이지마다 할 일	페이지별로 라이브 ID를 넣어야 함	코드 수정 없이 라이브가 열릴 때마다 자동 반영
추천 상황	기획전·상품 상세처럼 보여줄 라이브가 정해진 페이지	홈·목록처럼 지금 하는 라이브를 항상 노출하고 싶을 때 (홈 플로팅)

JavaScript — 라이브 ID 지정

window.SauceLiveLib.setInit({ broadcastId: '라이브ID를 입력해주세요' });
window.SauceLiveLib.setFloatingType({ type: 'basic' });
window.SauceLiveLib.load();

JavaScript — 진행 중인 라이브 자동 선택 (홈 플로팅)

window.SauceLiveLib.setOnAirInit({ partnerId: '파트너ID를 입력해주세요' });
window.SauceLiveLib.setFloatingType({ type: 'basic' });
window.SauceLiveLib.load();

📌 파트너 ID는 계약 완료 후 모비두 담당자로부터 발급받는 값입니다. 라이브 ID처럼 라이브마다 달라지지 않고 고객사당 하나로 고정되므로, 한 번 심어두면 이후 라이브가 열릴 때마다 별도 작업 없이 자동으로 노출됩니다.

⚠️ 방송은 페이지가 로드될 때 한 번만 선택됩니다. 시청자가 페이지를 열어둔 상태에서 다른 라이브가 새로 시작해도 자동으로 갈아타지 않습니다. 새 라이브는 페이지를 다시 열 때 반영됩니다.

⚠️ 두 함수를 함께 호출하지 마세요. 나중에 호출한 쪽이 앞의 설정을 덮어씁니다. 또한 setInit에 broadcastId가, setOnAirInit에 partnerId가 없으면 초기화가 중단되고 브라우저 콘솔에 오류가 남습니다.

작은 창 UI 레이아웃

플로팅 플레이어 위에 무엇을 그릴지를 layout.type으로 선택합니다. 시청 제어 버튼을 그대로 노출하는 control과, LIVE 배지만 얹어 최소한으로 노출하는 badge 두 가지입니다.

📌 기본값은 control이라 기존 코드는 그대로 두어도 동작이 바뀌지 않습니다. 배지형이 필요할 때만 layout을 추가하세요.

비교 항목	🎛 컨트롤형 `control` (기본)	🔴 배지형 `badge`
작은 창 위에	닫기·음소거·확대 버튼	LIVE 배지 + 닫기(×) 버튼
영상을 탭하면	재생 / 일시정지	전체화면으로 전환
버튼 구성 변경	가능 (`layout.buttonList`)	불가 — 버튼이 없는 구성
배지 이미지 교체	해당 없음	가능 (`layout.badgeImageUrl`)
배지 표시 조건	해당 없음	실제 방송 중일 때만 표시 (편성표 상태에서는 노출 안 됨)
추천 상황	시청 중 제어(음소거·확대)를 바로 쓸 수 있게 하고 싶을 때	홈·목록처럼 화면을 덜 가리면서 라이브 중임을 알리고 싶을 때

JavaScript — 컨트롤형 레이아웃

window.SauceLiveLib.setInit({ broadcastId: '라이브ID를 입력해주세요' });
window.SauceLiveLib.setFloatingType({
  type: 'basic',
  layout: {
    type: 'control',               // 기본값 — layout 자체를 생략해도 동일
    buttonList: ['exit']           // 선택 — 닫기 버튼만 노출
  }
});
window.SauceLiveLib.load();

JavaScript — 배지형 레이아웃

window.SauceLiveLib.setInit({ broadcastId: '라이브ID를 입력해주세요' });
window.SauceLiveLib.setFloatingType({
  type: 'basic',
  layout: {
    type: 'badge',
    badgeImageUrl: 'https://example.com/live-badge.png'  // 선택 — 미설정 시 기본 LIVE 배지
  }
});
window.SauceLiveLib.load();

배지 이미지 교체 시 확인할 것 — .png · .svg만 지원

항목	기준
지원 형식	`.png` · `.svg` — `.jpg`/`.jpeg`는 사용할 수 없습니다. 배경을 투명하게 만들 수 없어 배지 주변에 사각형 배경이 남기 때문입니다.
권장 크기	높이 24px 기준으로 표시되며, 가로는 최대 80px까지 노출됩니다. 비율은 유지된 채 맞춰집니다.
실패 시 동작	이미지 로딩이 3초를 넘기거나 실패하면 기본 LIVE 배지로 자동 대체됩니다. 배지가 아예 사라지지는 않습니다.

⚠️ 레이아웃에 맞지 않는 옵션은 무시됩니다. 배지형에 buttonList를 주거나 컨트롤형에 badgeImageUrl을 주면 해당 값만 조용히 버려지고 브라우저 콘솔에 경고가 남습니다. 설정이 반영되지 않으면 콘솔을 먼저 확인하세요.

세부 옵션 커스텀

플로팅 플레이어의 크기·위치·UI를 상세하게 설정할 수 있습니다. 아래 옵션은 초기화 방식(setInit · setOnAirInit)과 UI 레이아웃(컨트롤형 · 배지형)에 관계없이 동일하게 적용됩니다. 전체 파라미터는 파라미터 레퍼런스 — setFloatingType을 참고하세요.

파라미터	타입	필수	기본값	설명
type	'basic' \| 'scroll'	필수	—	플로팅 모드 타입
size	{ width, height? }	선택	—	플로팅 플레이어 크기. CSS 값으로 지정합니다. (예: `{ width: '135px', height: '230px' }`)
position	{ position, offsetX?, offsetY? }	선택	`bottom right`	플로팅 노출 위치. `'top left'` · `'top right'` · `'bottom left'` · `'bottom right'` 중 선택 기본 20px 여백이 적용되며, `offsetX`/`offsetY`로 미세 조정할 수 있습니다.
restrictionArea	{ element? \| elementId? }	선택	—	플로팅 플레이어가 이동할 수 있는 영역을 특정 HTML 요소 안으로 제한합니다.
layout	{ type, badgeImageUrl?, buttonList? }	선택	`{ type: 'control' }`	작은 창 위에 그릴 UI를 지정합니다. `type` — `'control'`(기본, 버튼형) 또는 `'badge'`(LIVE 배지형) `badgeImageUrl` — 배지형 전용, 배지 이미지 교체 `buttonList` — 컨트롤형 전용, 노출할 버튼 지정. `'exit'` 닫기 · `'mute'` 음소거 · `'fullscreen'` 확대. 미설정 시 기본 3개 자세한 내용은 위 작은 창 UI 레이아웃 참고.

⚠️ layout.buttonList는 1개 또는 3개만 지정하세요. 2개만 지정하면 기본 3개 구성(['exit','mute','fullscreen'])으로 되돌아갑니다. 버튼 2개용 레이아웃이 없어 의도적으로 그렇게 처리됩니다.

JavaScript — 커스텀 옵션 예시

window.SauceLiveLib.setInit({ broadcastId: '라이브ID를 입력해주세요' });
window.SauceLiveLib.setFloatingType({
  type: 'basic',
  size: { width: '135px', height: '230px' },
  restrictionArea: { element: document.body },
  position: { position: 'bottom right' },
  layout: { type: 'control', buttonList: ['exit'] }  // 닫기 버튼만 노출
});
window.SauceLiveLib.load();

📌 드래그와 스냅(자동 정렬)은 기본 플로팅(basic) 전용입니다. 기본 플로팅에서는 시청자가 플로팅 플레이어를 끌어서 옮길 수 있고, 손을 떼면 화면 모서리(상단 좌/우, 하단 좌/우) 중 가장 가까운 곳으로 자동 정렬됩니다. 별도 설정 없이 적용되며, restrictionArea로 이동 영역을 제한한 경우 그 영역의 모서리를 기준으로 정렬됩니다.
스크롤 플로팅(scroll)은 위치가 고정되어 시청자가 옮길 수 없습니다. 단 position으로 노출 위치를 지정하는 것은 두 모드 모두 가능합니다 — "개발자가 위치를 정하는 것"과 "시청자가 옮기는 것"은 다른 기능입니다.

버튼 동작 커스텀 (브릿지 이벤트)

닫기·확대 버튼의 기본 동작을 취소하고 직접 정의한 함수로 대체할 수 있습니다. 아래 함수명을 전역으로 선언하면 기본 동작이 자동으로 비활성화됩니다.

함수명	설명
sauceflexFloatingModeFullscreen	확대 버튼의 기본 동작(리다이렉트)이 취소되고 선언된 함수가 실행됩니다.
sauceflexFloatingModeExit	닫기 버튼의 기본 동작이 취소되고 선언된 함수가 실행됩니다. 컨트롤형·배지형 레이아웃 모두 적용됩니다.
sauceflexFloatingTogglePlay	정지/재생 버튼의 기본 동작을 커스텀합니다.

📌 닫기 버튼의 기본 동작(sauceflexFloatingModeExit를 선언하지 않았을 때)은 플로팅 모드에 따라 다릅니다. 기본 플로팅은 플레이어가 화면에서 완전히 제거되어 페이지를 다시 열어야 노출되고, 스크롤 플로팅은 숨겨질 뿐이라 원래 플레이어 위치로 스크롤하면 다시 나타납니다.

JavaScript — 버튼 동작 커스텀 예시

// ⚠️ 함수 내부에서 직접 호출하지 마세요
function sauceflexFloatingModeFullscreen() {
  // 확대 버튼 클릭 시 실행할 커스텀 동작을 정의합니다
  console.log('확대 버튼 클릭');
}
function sauceflexFloatingModeExit() {
  // 닫기 버튼 클릭 시 실행할 커스텀 동작을 정의합니다
  console.log('닫기 버튼 클릭');
}

window.SauceLiveLib.setInit({ broadcastId: '라이브ID를 입력해주세요' });
window.SauceLiveLib.setFloatingType({ type: 'basic' });
window.SauceLiveLib.load();

⚠️ 주의 — 커스텀 함수는 전역으로 선언만 해주세요. 함수 내부에서 직접 호출하면 의도하지 않은 동작이 발생할 수 있습니다.

이벤트 태깅 및 인터랙션 추적

플로팅 플레이어 내 버튼과 컨트롤에는 고정된 data-action 속성이 부여되어 있습니다. 이를 활용해 Adobe Analytics 등의 분석 도구로 사용자 인터랙션을 추적할 수 있습니다.

이벤트	data-action 값	설명
플로팅 닫기	floating-close	닫기 버튼 클릭 (컨트롤형·배지형 공통)
LIVE 배지 클릭	floating-live-badge	배지형 레이아웃의 LIVE 배지 클릭
플로팅 풀스크린	floating-fullscreen	확대 버튼 클릭 (원래 플레이어로 이동)
플로팅 음소거	floating-mute-on / floating-mute-off	음소거 상태에 따라 전환
영상 정지 / 재생	floating-pause / floating-play	플레이어의 재생 상태 변화

JavaScript — Analytics 이벤트 태깅 예시

const sauceLiveEl = document.getElementById('sauce_live');
sauceLiveEl?.addEventListener('click', function(event) {
  const action = event.target.getAttribute('data-action');

  if (action === 'floating-close') {
    // 닫기 이벤트 트래킹 코드 추가
  }
  if (action === 'floating-fullscreen') {
    // 확대 이벤트 트래킹 코드 추가
  }
  if (action === 'floating-mute-on') {
    // 음소거 이벤트 트래킹 코드 추가
  }
  if (action === 'floating-pause') {
    // 일시정지 이벤트 트래킹 코드 추가
  }
});

완성 예시 코드

앞에서 고른 조합을 그대로 붙여 쓸 수 있는 전체 코드입니다.

기본 플로팅 예시

가장 기본이 되는 구성입니다. broadcastId를 교체하면 바로 실행할 수 있습니다.

HTML — 완성 예시

<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, viewport-fit=cover" />
  <script type="text/javascript"
          src="https://player.sauceflex.com/static/js/SauceLiveLib.js"></script>
  <style>
    html, body { margin: 0; padding: 0; background-color: #333; }
  </style>
</head>
<body>
  <div id='sauce_live'></div>
</body>
<script>

window.addEventListener("DOMContentLoaded", () => {
  window.SauceLiveLib.setInit({ broadcastId: '라이브ID를 입력해주세요' });
  window.SauceLiveLib.setFloatingType({ type: 'basic' });
  window.SauceLiveLib.load();
});
</script>
</html>

홈 플로팅 예시

홈처럼 "지금 하는 라이브가 있으면 알려주는" 화면에 적합한 구성입니다. partnerId를 교체하면 바로 실행할 수 있습니다.

HTML — 홈 플로팅 완성 예시

<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, viewport-fit=cover" />
  <script type="text/javascript"
          src="https://player.sauceflex.com/static/js/SauceLiveLib.js"></script>
  <style>
    html, body { margin: 0; padding: 0; background-color: #333; }
  </style>
</head>
<body>
  <div id='sauce_live'></div>
</body>
<script>

window.addEventListener("DOMContentLoaded", () => {
  window.SauceLiveLib.setOnAirInit({ partnerId: '파트너ID를 입력해주세요' });
  window.SauceLiveLib.setFloatingType({
    type: 'basic',
    layout: { type: 'badge' }
  });
  window.SauceLiveLib.load();
});
</script>
</html>

📌 기본 플로팅 type: 'basic'

📜 스크롤 플로팅 type: 'scroll'

📌 기본 플로팅 `type: 'basic'`

📜 스크롤 플로팅 `type: 'scroll'`