플로팅 플레이어

플로팅 플레이어 — 소스라이브 플레이어

플로팅 기능을 사용하면 사용자가 상품 페이지나 다른 페이지로 이동하더라도 플레이어를 작은 화면으로 계속 시청할 수 있습니다. 두 가지 플로팅 모드를 제공합니다.

⏱ 예상 소요 시간: 15~20분

📋 사전 조건: 라이브러리 설치 및 플레이어 실행 확인

플로팅 모드 선택

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();

세부 옵션 커스텀

플로팅 사이즈, 위치, 노출 버튼 등을 상세하게 설정할 수 있습니다. 전체 파라미터는 파라미터 레퍼런스 — 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/Y로 미세 조정 가능.
restrictionArea	{ element? \| elementId? }	선택	—	플로팅 플레이어가 이동할 수 있는 영역을 특정 HTML 요소 안으로 제한합니다.
buttonList	string[]	선택	`['exit','mute','fullscreen']`	노출할 버튼 지정. `'exit'` 닫기, `'mute'` 음소거, `'fullscreen'` 확대. 미설정 시 기본 3개 버튼 노출.

JavaScript — 커스텀 옵션 예시

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

📌 스냅(자동 정렬) — 플로팅 플레이어를 드래그하면 화면 모서리(상단 좌/우, 하단 좌/우) 중 가장 가까운 위치로 자동 정렬됩니다. 별도 설정 없이 기본 적용되며, restrictionArea로 이동 영역을 제한한 경우 그 영역의 모서리를 기준으로 정렬됩니다.

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

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

함수명	설명
sauceflexFloatingModeFullscreen	확대 버튼의 기본 동작(리다이렉트)이 취소되고 선언된 함수가 실행됩니다.
sauceflexFloatingModeExit	닫기 버튼의 기본 동작이 취소되고 선언된 함수가 실행됩니다.
sauceflexFloatingTogglePlay	정지/재생 버튼의 기본 동작을 커스텀합니다.

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	닫기 버튼 클릭
플로팅 풀스크린	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>

다음 단계

🔗 브릿지 이벤트 연동 — 플레이어와 자사몰 간 이벤트 연동 시작하기

→

📌 기본 플로팅 type: 'basic'

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

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

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