라이브러리 파라미터 레퍼런스

라이브러리 파라미터 레퍼런스 — 소스라이브 플레이어

📖 참조 문서 ✅ 사전조건: 라이브러리 설치 완료

호출 순서 setInit() → setMemberObject() 선택 / setMemberToken() 선택 → setFloatingType() 선택 → load()

초기화

setInit()

인증 — 로그인 사용자에게만 필요

setMemberObject()
setMemberToken()

플로팅 플레이어

setFloatingType()

초기화

SauceLiveLib.setInit()

플레이어 초기화 함수입니다. 라이브 ID 등 필수 설정값을 전달합니다. load() 호출 이전에 실행해야 합니다.

사용 예시 →

파라미터	타입	필수	기본값	설명
broadcastId	String	필수	—	어드민에서 확인한 라이브 ID
id	String	선택	`sauce_live`	플레이어를 표시할 컨테이너 요소의 ID. 미설정 시 `sauce_live`로 자동 지정됩니다.
env	String	선택	`'production'`	테스트 환경 설정. `'stage'`로 설정 시 stage 라이브에 접근합니다. 미설정 시 운영 환경으로 처리됩니다.
platform	String	선택	—	웹빌더 식별값. 카페24·메이크샵 등 웹빌더 연동 시 사용합니다. `'CAFE24'` · `'MAKESHOP'` · `'SHOPBY'` · `'GODOMALL'` · `'IMWEB'` 중 선택하며, 직접 구축한 자사몰은 설정하지 않습니다.

JavaScript

window.SauceLiveLib.setInit({
  broadcastId: '라이브ID를 입력해주세요',         // 필수
  id: 'sauce_live',            // 선택 — 컨테이너 ID (기본값: 'sauce_live')
  env: 'stage',               // 선택 — stage 테스트 시 사용
});

SauceLiveLib.setOnAirInit()

라이브 ID 대신 파트너 ID로 초기화합니다. 진행 중인 라이브 중 가장 최근에 시작한 라이브를 자동으로 선택합니다. 홈·목록처럼 띄울 라이브가 정해져 있지 않은 화면(홈 플로팅)에 사용합니다. setInit()과 둘 중 하나만 호출합니다.

사용 예시 →

파라미터	타입	필수	기본값	설명
partnerId	String	필수	—	계약 완료 후 발급받은 파트너 ID. 라이브마다 바뀌지 않는 고정값입니다.
id	String	선택	`sauce_live`	플레이어를 표시할 컨테이너 요소의 ID. 미설정 시 `sauce_live`로 자동 지정됩니다.
env	String	선택	`'production'`	테스트 환경 설정. `'stage'`로 설정 시 stage 라이브에 접근합니다. 미설정 시 운영 환경으로 처리됩니다.
platform	String	선택	—	`setInit()`과 동일합니다.

JavaScript

window.SauceLiveLib.setOnAirInit({
  partnerId: '파트너ID를 입력해주세요',          // 필수
  id: 'sauce_live',            // 선택 — 컨테이너 ID (기본값: 'sauce_live')
  env: 'stage',               // 선택 — stage 테스트 시 사용
});

📌 진행 중인 라이브가 없으면 아무것도 표시되지 않습니다(오류가 아닙니다). 또한 방송은 load() 시점에 한 번만 선택되므로, 페이지를 열어둔 상태에서 새 라이브가 시작되어도 자동으로 바뀌지 않습니다.

인증

SauceLiveLib.setMemberObject()

간편 인증 방식으로 사용자 정보를 플레이어에 전달합니다. load() 호출 이전에 실행해야 합니다.

인증 선택 가이드 →

파라미터	타입	필수	기본값	설명
memberId	String	필수	—	고객사 고유 회원 ID
nickName	String	필수	—	채팅창에 표시되는 닉네임
memberType	"0" \| "1"	선택	—	회원 구분. `"1"` = 회원, `"0"` = 비회원
age	String	선택	—	통계 데이터 수집용 나이대. (예: `'10'`, `'20'`, `'30'` …)
gender	String	선택	—	통계 데이터 수집용 성별. `'m'` 남성, `'w'` 여성

JavaScript

window.SauceLiveLib.setMemberObject({
  memberId: 'user_001',   // 필수
  nickName: '홍길동',     // 필수
  memberType: '1',       // 선택 — 회원
  age: '20',             // 선택 — 통계용
  gender: 'm',          // 선택 — 통계용
});

⚠️ 보안 주의 — setMemberObject()는 클라이언트에서 회원 ID를 직접 전달하므로 위변조 방지가 되지 않습니다. 보안이 중요한 서비스라면 setMemberToken()(JWT 인증)을 사용하세요. 인증 방식 비교 →

SauceLiveLib.setMemberToken()

JWT 인증 방식으로 서버에서 발급한 토큰을 플레이어에 전달합니다. ID 위변조를 방지합니다. load() 호출 이전에 실행해야 합니다.

인증 선택 가이드 →

파라미터	타입	필수	기본값	설명
token	String	필수	—	서버에서 RSA Private Key로 서명한 JWT 토큰 (Base64 인코딩). 생성 방법은 JWT 토큰 생성 가이드에 있습니다.

JavaScript

window.SauceLiveLib.setMemberToken('서버에서 발급한 JWT 토큰');

🔑 PEM 키(RS256 개인키) 사전 발급 필요 — JWT 토큰 서명에는 소스라이브가 발급한 RS256 개인키가 필요합니다. 아직 발급받지 않았다면 고객성공팀에 문의하세요. 발급받은 키는 반드시 서버에서만 보관하세요.

📄 JWT 토큰 생성 방법(필수 payload 필드, 헤더 규격 등)은 API 문서에 있습니다. → JWT Token 생성

플로팅 플레이어

SauceLiveLib.setFloatingType()

플로팅 플레이어 모드와 세부 옵션을 설정합니다. load() 호출 이전에 실행해야 합니다.

사용 예시 →

파라미터	타입	필수	기본값	설명
type	'basic' \| 'scroll'	필수	—	플로팅 모드 선택. `'basic'`: 페이지 로드 시 즉시 플로팅 플레이어로 표시. `'scroll'`: 플레이어가 화면에서 벗어날 때 플로팅 플레이어로 전환.
size	{ width: String; height?: String }	선택	—	플로팅 플레이어 크기. CSS 값으로 지정합니다. (예: `{ width: '135px', height: '230px' }`)
position	{ position: String; offsetX?: number; offsetY?: number }	선택	`bottom right`	플로팅 노출 위치. `position` — `'top left'` · `'top right'` · `'bottom left'` · `'bottom right'` 중 선택 기본 20px 여백이 적용되며, `offsetX`/`offsetY`로 미세 조정
restrictionArea	{ element?: Element; elementId?: String }	선택	—	플로팅 플레이어가 이동할 수 있는 영역을 특정 HTML 요소 안으로 제한합니다. `element`와 `elementId` 중 하나만 사용합니다. 이동은 `type: 'basic'`에서만 가능하므로 `'scroll'`에서는 의미가 없습니다.
layout	{ type: String; badgeImageUrl?: String; buttonList?: string[] }	선택	`{ type: 'control' }`	작은 창 위에 그릴 UI 구성. 아래 layout 하위 파라미터 표 참고.

layout 하위 파라미터

파라미터	타입	필수	기본값	설명
type	'control' \| 'badge'	필수	`'control'`	`'control'` — 닫기·음소거·확대 버튼 표시. 영상을 탭하면 재생/일시정지 `'badge'` — LIVE 배지와 닫기(×) 버튼만 표시. 영상을 탭하면 전체화면으로 전환
badgeImageUrl	String	선택	—	`'badge'` 전용. LIVE 배지 대신 사용할 이미지 주소. `.png`·`.svg`만 지원 (`.jpg`/`.jpeg`는 투명 배경 불가로 거부) 높이 24px · 최대 폭 80px로 표시 로딩이 3초를 넘기거나 실패하면 기본 LIVE 배지로 대체
buttonList	string[]	선택	`['exit','mute','fullscreen']`	`'control'` 전용. 노출할 버튼 목록. 1개 또는 3개만 유효하며, 2개를 지정하면 기본 3개 구성으로 되돌아갑니다.

JavaScript

window.SauceLiveLib.setFloatingType({
  type: 'basic',                          // 필수 — 'basic' | 'scroll'
  size: { width: '135px', height: '230px' }, // 선택
  position: { position: 'bottom right' },    // 선택 (기본: 'bottom right')
  restrictionArea: { element: document.body }, // 선택
  layout: {                                // 선택 (기본: { type: 'control' })
    type: 'control',
    buttonList: ['exit'],                    // 닫기 버튼만 노출
  },
});

📌 전달하지 않은 항목은 기존 값이 유지됩니다. 위치만 바꾸려면 position만 전달하면 되고, 버튼 구성·크기·제한 영역은 그대로 남습니다. 또한 레이아웃에 맞지 않는 값('badge'에 buttonList, 'control'에 badgeImageUrl)은 무시되고 브라우저 콘솔에 경고가 남습니다.

다음 단계

🔗 URL 연동 가이드 — 스크립트 없이 라이브 URL 로 실행하기

→