자주 묻는 질문 (FAQ)
소스라이브 플레이어 연동 중 자주 묻는 질문과 답변을 카테고리별로 정리했습니다. 질문을 클릭하면 답변이 펼쳐집니다.
<head>와 <body> 중 어디에 넣어야 하나요?
설치
▾
둘 다 가능합니다. <head>에 넣으면 페이지 로드 시점에 라이브러리가 미리 준비되어 더 안정적입니다. <body> 하단에 넣어도 동작하지만, 스크립트 실행 전에 SauceLiveLib을 호출하면 오류가 발생할 수 있습니다.
<!-- 권장: head에 삽입 --> <head> <script src="https://player.sauceflex.com/static/js/SauceLiveLib.js"></script> </head>
소스라이브 어드민 → 라이브 편성 → 해당 라이브의 송출 정보에서 확인할 수 있습니다. 테스트 라이브는 stage 환경에서 생성하고, env: 'stage' 옵션을 함께 전달하세요.
window.SauceLiveLib.setInit({ broadcastId: '어드민에서_확인한_ID', env: 'stage' // 테스트 환경에서만 사용 })
연동 방식은 필요한 기능에 따라 선택하세요.
- 라이브러리 방식 — 플로팅 기능, 브릿지 이벤트 제어, 사용자 인증 등 고급 기능이 필요할 때. 스크립트 한 줄 삽입 후 JS로 제어합니다.
- URL 방식 — 설치 없이 라이브 URL만으로 빠르게 연동할 때. 단, 고급 기능 사용 불가.
id="sauce_live"인 컨테이너 요소에 CSS로 직접 지정합니다. 플레이어는 컨테이너 크기에 맞게 자동으로 채워집니다. 전체 화면으로 사용하려면 width: 100%; height: 100vh;를 적용하세요.
/* CSS */ #sauce_live { width: 100%; height: 100vh; position: fixed; top: 0; left: 0; z-index: 9999; }
SPA 환경에서는 페이지 전환 시 컨테이너 DOM이 사라질 수 있어 플레이어가 비정상 종료될 수 있습니다. 다음 사항을 확인하세요.
- 컴포넌트 마운트 이후(
useEffect,mounted)에load()를 호출하세요. - 컴포넌트 언마운트 시 컨테이너를 DOM에서 제거하기 전 플레이어를 정리하세요.
- 브릿지 이벤트
message리스너는 컴포넌트 언마운트 시removeEventListener로 반드시 해제하세요.
setMemberObject와 setMemberToken의 차이는 무엇인가요?
인증
▾
두 함수 모두 사용자 정보를 플레이어에 전달하지만 보안 수준이 다릅니다.
- setMemberObject — 사용자 정보를 JS 객체로 직접 전달. 빠르고 간편하지만 클라이언트 측 위변조 가능성이 있습니다.
- setMemberToken — 서버에서 RS256 개인키로 서명한 JWT를 전달. 위변조 방지가 적용된 권장 방식입니다.
반드시 서버에서 생성해야 합니다. JWT 서명에 사용하는 RS256 개인키(PEM)가 클라이언트에 노출되면 누구나 임의의 사용자로 위장할 수 있습니다. 서버에서 토큰을 생성한 뒤 클라이언트로 전달하는 방식으로 구현하세요.
// ❌ 클라이언트에서 직접 PEM 키 사용 — 절대 금지 // ✅ 서버 API를 호출하여 토큰을 받아옴 const { token } = await fetch('/api/live-token').then(r => r.json()) window.SauceLiveLib.setMemberToken(token)
아래 항목을 순서대로 확인하세요.
- JWT Header에
"typ": "JWT"와"alg": "RS256"이 모두 포함되어 있나요? - 소스라이브 어드민에서 발급받은 PEM 키로 서명했나요?
- Payload의 필수 필드(
partnerId,memberId,nickName,memberType)가 모두 있나요? setInit()호출 이후에setMemberToken()을 호출했나요?
네. 인증 없이 시청 가능합니다. setMemberObject()나 setMemberToken()을 호출하지 않으면 자동으로 로그인 하지 않은 상태로 동작합니다. 단, 채팅·쿠폰 등 로그인이 필요한 기능은 사용할 수 없습니다.
// 게스트 모드 — 인증 함수 없이 바로 load() window.SauceLiveLib.setInit({ broadcastId: '라이브ID' }) window.SauceLiveLib.load()
상품 클릭은 자사몰에서 브릿지 이벤트 리스너를 직접 구현해야 동작합니다. 소스라이브 플레이어는 이벤트를 전송할 뿐, 페이지 이동 등의 처리는 고객사 코드에서 수행합니다.
window.addEventListener('message', (e) => { if (typeof e.data !== 'string') return const { key, params } = JSON.parse(e.data) if (key === 'sauceflexMoveProduct') { window.location.href = params.linkUrl } })
다음 원인을 확인하세요.
- 중첩 iframe 구조 — 플레이어가 다른 iframe 내부에 삽입된 경우 이벤트가 누락될 수 있습니다. 최상위 페이지에서 직접 삽입하세요.
- 리스너 등록 위치 —
load()호출 이전에 리스너를 등록했는지 확인하세요. - 메시지 검증 조건 —
typeof e.data === 'string'조건이 잘못 설정된 경우 모든 메시지를 걸러낼 수 있습니다.
쿠폰 클릭 이벤트 유형(couponType)에 따라 브릿지 이벤트 구현 여부가 달라집니다.
link/newWindow— 브릿지 이벤트에서sauceflexMoveCouponcase를 구현해야 합니다.download/custom— 브릿지 이벤트가 없으면 동작하지 않습니다. 반드시 구현이 필요합니다.apiDownload— 어드민에 API URL이 등록된 경우 브릿지 이벤트 없이 자동 처리됩니다.
플로팅 모드에서 전체 화면 전환은 브릿지 이벤트 콜백 함수를 통해 처리합니다. 전역에 아래 두 함수를 정의하지 않으면 동작하지 않습니다.
// 플로팅 → 전체 화면 전환 window.sauceflexFloatingModeFullscreen = () => { document.getElementById('sauce_live').style.display = 'block' } // 전체 화면 → 플로팅 축소 window.sauceflexFloatingModeExit = () => { document.getElementById('sauce_live').style.display = 'none' }
네. 소스라이브는 방송 종료 후 자동으로 VOD를 제공합니다. 동일한 broadcastId로 접속하면 녹화된 영상이 재생됩니다. VOD 제공 여부는 어드민에서 방송별로 설정할 수 있습니다.
네. 네이티브 앱의 WebView에서 플로팅 기능을 사용하려면 각 플랫폼별 사전 설정이 필요합니다.
- iOS —
WKWebView에서allowsInlineMediaPlayback = true설정 필요 - Android —
WebSettings에서javaScriptEnabled,mediaPlaybackRequiresUserGesture등 설정 필요
iframe으로 연동한 경우 allow 속성에 fullscreen이 포함되어 있는지 확인하세요. 라이브러리 방식에서는 컨테이너에 position: fixed; width: 100%; height: 100%;를 설정하면 전체 화면처럼 동작합니다.
<!-- iframe 방식: allow 속성 확인 --> <iframe allow="autoplay; fullscreen; picture-in-picture" ...></iframe>
Updated about 24 hours ago