GuidesAPI GuideChangelog
Log In
Guides

브릿지 이벤트 레퍼런스

자사몰에서 처리할 수 있는 브릿지 이벤트의 이름과 이벤트 값 구조입니다. 자사몰 페이지에서는 소스라이브 플레이어 웹 SDK의 SauceLive.Player('on', …)로 이벤트를 수신하고, 앱이 플레이어 주소를 웹뷰로 바로 열면 Android @JavascriptInterface, iOS WKScriptMessageHandler로 수신합니다.

브릿지 이벤트 레퍼런스 — 소스라이브 플레이어
📖 참조 문서
📋 사전 조건: 브릿지 이벤트 연동 완료
📘 이벤트는 SauceLive.Player('on', 이벤트 이름, 처리 함수)로 수신하고, 명령은 SauceLive.Player('명령', 인자)로 호출합니다. 위치 · 열림 · 오류 같은 나머지 이벤트와 시작 옵션은 라이브러리 파라미터 레퍼런스에 있습니다. 값 표의 「필수」는 항상 들어 있는 필드이고, 타입에 null이 있으면 값이 null일 수 있습니다.
앱이 플레이어 주소를 웹뷰로 바로 열 때 주고받는 sauceflex… 이름은 맨 아래 앱 웹뷰 이름 절에 있습니다.
🔵 라이프사이클 이벤트 — 사용자 액션 없이 플레이어가 자동 전송
ready 연결 완료
플레이어와 연결이 완료되면 자동으로 전송됩니다. 시청자의 방송 입장 시점을 감지하는 데 활용합니다. saucelive-player.min.js 스크립트가 실행되기 전에 호출한 명령은 Promise를 돌려주지 않으므로, 결과를 받을 명령은 페이지가 로드된 뒤에 호출하세요.
필드타입필수설명
protocol1 | 2필수플레이어 통신 규약 버전
broadcastStatusChange 방송 상태 변경
방송 상태가 변경될 때마다 자동으로 전송됩니다. broadcastStateCode를 통해 현재 방송 상태를 파악할 수 있습니다.
필드타입필수설명
broadcastIdString필수라이브 ID
broadcastStateCodeString | null필수방송 상태 코드. 예: 'onair' · 'ready' · 'vod'
firstPlay 첫 재생
시청자가 방송에 입장한 후 영상이 최초로 재생될 때 한 번 전송됩니다. 플레이어의 로딩 화면이 사라진 뒤입니다. 첫 재생 시점 기록이나 온보딩 UI 표시 등에 활용합니다.
필드타입필수설명
값 없음
pvCountChange 조회 수 변경
방송의 누적 조회 수가 바뀔 때마다 전송됩니다. 누적 조회 수를 자사몰 UI에 표시하는 데 활용합니다.
필드타입필수설명
pvCountNumber | null필수누적 조회 수. 집계 전이면 null
timeUpdate 재생 위치 변경
라이브 또는 VOD의 재생 위치가 변경될 때마다 지속적으로 전송됩니다. 시청 시간 추적 등에 활용합니다.
필드타입필수설명
currentTimeNumber필수영상 처음부터 센 재생 위치(초)
muteChange 소리 상태 변경
플레이어의 음소거 상태가 변경될 때마다 전송됩니다. 자사몰에서 음소거 상태에 따라 별도 UI를 제어할 때 활용합니다.
필드타입필수설명
isMutedBoolean필수true: 소리 꺼짐 / false: 소리 켜짐
rewardCouponIssue 리워드 쿠폰 달성
리워드 조건 시간을 채웠을 때 달성한 쿠폰 목록과 함께 전송됩니다. 커스텀 쿠폰을 쓰도록 따로 설정한 파트너에만 전송되므로, 쓰려면 고객성공팀에 문의하세요. 달성한 쿠폰을 자사몰에서 발급할 때 활용합니다. 리워드 흐름은 리워드 연동에 있습니다.
필드타입필수설명
couponListArray필수달성한 쿠폰 목록
🟠 사용자 액션 이벤트 — 시청자가 특정 UI를 클릭할 때 전송
⚠️ 등록한 클릭은 자사몰 코드가 모두 처리합니다. 등록하면 아래 「등록하지 않으면」 동작은 실행되지 않습니다. 이벤트 값의 broadcastId로 방송마다 처리를 구분할 수 있습니다.
productClick 상품 클릭
플레이어 내 상품을 클릭할 때 전송됩니다. 등록하지 않으면 웹 SDK가 linkUrl로 이동합니다. 자세한 구현은 상품 클릭 연동 가이드에 있습니다.
필드타입필수설명
broadcastIdString필수라이브 ID
linkUrlString | null필수상품 페이지 주소
priceNumber | String | null필수상품 가격
externalProductIdString | null필수어드민에 등록한 외부 상품 코드. 등록하지 않은 상품은 null
isSoldoutBoolean필수품절 여부
scheme{ url, webUrl }선택앱 웹뷰로 연 자사몰 페이지에서, 어드민에 앱스킴을 넣은 항목을 클릭할 때만 들어 있습니다. url 앱스킴 · webUrl 웹 주소
productLayerClick 상품 레이어 클릭
플레이어 내 상품 레이어를 클릭할 때 전송됩니다. 등록하지 않으면 플레이어가 처리합니다.
필드타입필수설명
broadcastIdString필수라이브 ID
externalProductIdString | null필수외부 상품 코드
cartClick 장바구니 클릭
플레이어 내 상품의 장바구니 버튼을 클릭할 때 전송됩니다. externalProductId로 자사몰 상품을 식별하고 장바구니 담기 처리를 수행합니다. 등록하지 않으면 플레이어가 상품 시트를 닫습니다.
필드타입필수설명
broadcastIdString필수라이브 ID
externalProductIdString | null필수외부 상품 코드
bannerClick 배너 클릭
플레이어 내 배너를 클릭할 때 전송됩니다. 등록하지 않으면 웹 SDK가 linkUrl로 이동하고, tel: 배너는 휴대폰에서 전화를 겁니다. 다른 동작이 필요하면 등록해 커스텀 동작을 정의하세요.
필드타입필수설명
broadcastIdString필수라이브 ID
bannerIdString | null필수배너 ID
linkUrlString | null필수배너 링크 주소
scheme{ url, webUrl }선택앱 웹뷰로 연 자사몰 페이지에서, 어드민에 앱스킴을 넣은 항목을 클릭할 때만 들어 있습니다. url 앱스킴 · webUrl 웹 주소
slotBannerClick 슬롯 배너 클릭
슬롯 배너를 클릭할 때 전송됩니다. 등록하지 않으면 웹 SDK가 target에 따라 같은 창 또는 새 창으로 엽니다. 등록했다면 target으로 현재 창 또는 새 창 여부를 구분하세요.
필드타입필수설명
broadcastIdString필수라이브 ID
slotBannerIdString | null필수슬롯 배너 ID
urlString | null필수이동할 주소. 앱스킴 클릭이면 앱스킴 주소
target'BLANK' | 'SELF'필수'BLANK': 새 창 / 'SELF': 같은 창
scheme{ url, webUrl }선택앱 웹뷰로 연 자사몰 페이지에서, 어드민에 앱스킴을 넣은 항목을 클릭할 때만 들어 있습니다. url 앱스킴 · webUrl 웹 주소
couponClick 쿠폰 클릭
쿠폰 버튼 클릭 시 전송됩니다. couponType으로 처리 방식을 구분합니다. apiDownload 쿠폰은 전송되지 않습니다. 자세한 구현은 쿠폰 연동 가이드에 있습니다.
필드타입필수설명
broadcastIdString필수라이브 ID
couponTypeString | null필수'link' · 'newWindow' · 'download' · 'custom'
couponCodeString | null필수쿠폰 코드
couponIdString | null필수쿠폰 ID
couponNameString | null필수쿠폰 이름
linkUrlString | null필수이동할 주소
metaDataString | null필수사용자 정의 데이터(JSON 문자열)
scheme{ url, webUrl }선택앱 웹뷰로 연 자사몰 페이지에서, 어드민에 앱스킴을 넣은 항목을 클릭할 때만 들어 있습니다. url 앱스킴 · webUrl 웹 주소
rewardClick 리워드 클릭
리워드 달성 후 CLICK 버튼을 클릭할 때 전송됩니다. 등록하지 않으면 웹 SDK가 linkUrl로 이동합니다. 자세한 구현은 리워드 연동 가이드에 있습니다.
필드타입필수설명
broadcastIdString필수라이브 ID
linkUrlString | null필수리워드 연결 URL
shareClick 공유 클릭
공유하기 버튼 클릭 시 전송됩니다. 공유 URL과 방송 정보로 자사몰의 공유 기능을 구성할 때 등록하세요. 등록하지 않으면 웹 SDK가 플레이어를 연 자사몰 페이지 주소를 복사하거나 기기 공유 창을 띄웁니다.
필드타입필수설명
broadcastIdString필수라이브 ID
broadcastNameString | null필수방송 이름
broadcastThumbnailUrlString | null필수방송 썸네일 이미지 주소
linkUrlString | null필수방송 공유 주소
shortUrlString | null필수방송 단축 주소
loginClick 로그인 버튼 클릭
게스트가 채팅·쿠폰 등 로그인이 필요한 기능에 접근할 때 로그인 버튼을 클릭하면 전송됩니다. 로그인이 요청된 라이브·상점 정보가 함께 전달됩니다. 등록하지 않으면 로그인 버튼을 눌러도 이동하지 않으므로, 자사몰은 반드시 등록하세요. 자세한 구현은 로그인 연동 가이드에 있습니다.
필드타입필수설명
broadcastIdString필수라이브 ID
shopIdString | null필수상점 ID
shopNameString | null필수상점 이름
closeClick 닫기 클릭
플레이어의 닫기 버튼을 클릭할 때 전송됩니다. 등록하지 않으면 웹 SDK가 플레이어를 닫습니다. 이전 페이지로 이동하는 등 다른 처리가 필요할 때 등록하세요.
필드타입필수설명
broadcastIdString필수라이브 ID
pipClick PIP 버튼 (앱 웹뷰)
앱 웹뷰에서 PIP(Picture-in-Picture) 버튼 클릭 시 전송됩니다. 버튼은 어드민 PIP 설정을 켠 방송에서 보이고, 클릭 시 플레이어가 PIP 화면 배치로 바뀝니다. PIP 기능 자체는 앱에서 별도 개발이 필요합니다.
필드타입필수설명
broadcastIdString필수라이브 ID
floatingClick · floatingCloseClick · floatingFullscreenClick 플로팅 버튼
플로팅 플레이어의 버튼을 클릭할 때 전송됩니다. 등록하지 않았을 때의 동작은 버튼 동작 · 이벤트 추적에 있습니다.
필드타입필수설명
broadcastIdString필수라이브 ID
notificationRequest 알림 신청 · 해제
라이브 예고 플레이어에서 사용자가 알림 신청·해제를 클릭할 때 전송됩니다. 자사몰은 처리 결과를 respondToNotification 명령으로 플레이어에 다시 전송합니다. 전체 흐름은 라이브 알림 버튼 연동 가이드에 있습니다.
필드타입필수설명
broadcastIdString필수라이브 ID
requestIdString필수respondToNotification에 넘길 요청 ID
state'on' | 'off'필수신청 · 해제
programmingStartDtString | null필수라이브 시작 예정 시간(UTC)
programmingEndDtString | null필수라이브 종료 예정 시간(UTC)
🟢 명령 — 자사몰이 플레이어로 전송하고 Promise를 돌려받음
respondToNotification 알림 결과 돌려주기
자사몰의 알림 신청·해제 처리가 끝나면 결과와 함께 전송합니다. 실패·취소도 전송하세요. 플레이어는 결과를 받을 때까지 시간 제한 없이 알림 버튼을 잠급니다.
인자타입필수설명
requestIdString필수notificationRequest로 받은 요청 ID
result'success' | 'fail' | 'cancel'필수처리 결과. 그 밖의 값이면 INVALID_OPTIONS로 실패합니다
enterAsGuest 게스트로 들어가기
시청자를 게스트로 전환합니다. 자사몰 로그아웃을 플레이어에 반영할 때 사용합니다. logOut과 동작이 같습니다. 로그아웃 처리
인자타입필수설명
인자 없음
play · pause · playLive 재생 · 정지 · 라이브 지점
재생 · 정지 · 라이브 지점으로 이동합니다. 플레이어가 닫힌 동안 호출하면 NOT_OPEN으로 실패합니다.
인자타입필수설명
인자 없음
mute · unmute 소리 끄기 · 켜기
플레이어 소리를 끄거나 켭니다.
인자타입필수설명
인자 없음
restoreFocus 포커스 돌려놓기
플레이어 안 요소로 포커스를 돌려놓습니다.
인자타입필수설명
elementIdString선택닫힌 플레이어 창 이름. 그 창을 연 버튼으로 포커스가 돌아갑니다. 생략하면 포커스를 이동하지 않습니다.
예: 'share-bottom-sheet'(공유 버튼)
delayMsNumber선택돌려놓기까지 기다릴 시간(ms)
showToast 알림 문구 띄우기
플레이어 안에 알림 문구를 띄웁니다.
인자타입필수설명
문구String필수띄울 문구
전체 이벤트 리스너 예시

라이프사이클 이벤트를 console.log로 확인하는 디버깅용 리스너입니다. 개발 초기 단계용입니다. 클릭 이벤트는 실제 처리 함수를 만든 뒤 하나씩 등록하세요.

JavaScript — 이벤트 디버깅 리스너
// 라이프사이클 이벤트만 로그로 확인한다. 클릭 이벤트를 등록하면 그 클릭의 기본 동작이 실행되지 않는다
['ready', 'broadcastStatusChange', 'firstPlay', 'pvCountChange', 'timeUpdate', 'muteChange', 'rewardCouponIssue']
  .forEach((name) => {
    SauceLive.Player('on', name, (e) => console.log(name, e))
  })
앱 웹뷰 이름

앱이 플레이어 주소를 웹뷰로 바로 열 때 네이티브 브릿지로 주고받는 이름입니다. 위의 웹 SDK on() 이벤트·명령과는 다른 이름이고, 웹 SDK를 설치한 자사몰 페이지에서는 쓰지 않습니다. 웹 SDK 없이 플레이어를 iframe으로 넣은 페이지도 같은 이름을 씁니다. 앱이 그 이름을 등록하지 않았으면 부모 페이지가 postMessage로 받습니다(iframe 연동 가이드).
브릿지 등록과 보내는 방법은 앱 웹뷰 브릿지에 있습니다.

🟣 플레이어 → 앱: 플레이어가 호출하는 이름

플레이어가 앱 브릿지로 보내는 이름과 값입니다. 앱은 받을 이름만 등록하세요. 오른쪽 열은 웹 SDK를 설치한 자사몰 페이지에서 같은 일을 받는 이벤트입니다.
…Scheme 이름은 어드민에 앱스킴을 넣은 항목을 클릭할 때 호출됩니다. 앱은 url(쿠폰은 schemeUrl)의 앱스킴을 열고, 열지 못하면 webUrl로 이동하세요.

이름값자사몰 페이지에서는
sauceflexEnter없음ready
sauceflexBroadcastStatusbroadcastStateCodebroadcastStatusChange
sauceflexFirstPlay없음firstPlay
sauceflexUpdatePvCountpvCountpvCountChange
sauceflexSendPlayTimeposition(초)timeUpdate
sauceflexPlayerMuteStatusisMutemuteChange
sauceflexIssueCoupon쿠폰 목록(배열)rewardCouponIssue
sauceflexMoveLoginAndroid 없음(설정에 따라 일부 파트너는 JSON 문자열) · iOS broadcastId · shopId · shopName. 앱은 로그인 뒤 accessToken 쿼리를 붙인 플레이어 주소를 다시 불러옴loginClick
sauceflexMoveProductlinkUrl · broadcastIdx · price · externalProductId · isSoldoutproductClick
sauceflexProductAndroidScheme
sauceflexProductIosScheme
sauceflexMoveProduct의 linkUrl 대신 url(앱스킴) · webUrlproductClick
sauceflexMoveProductLayerexternalProductIdproductLayerClick
sauceflexMoveCartexternalProductIdcartClick
sauceflexMoveBannerlinkUrl · broadcastIdx · bannerIdbannerClick
sauceflexBannerAndroidScheme
sauceflexBannerIosScheme
url · broadcastIdx · bannerId · webUrlbannerClick
sauceflexMoveSlotBannerslotBannerId · broadcastId · url · webUrlTargetTypeCode('BLANK' · 'SELF')slotBannerClick
sauceflexSlotBannerAndroidScheme
sauceflexSlotBannerIosScheme
sauceflexMoveSlotBanner 값 · webUrl. url은 앱스킴slotBannerClick
sauceflexMoveCouponbroadcastIdx · couponType · couponCode · couponId · couponName · linkUrl · metaData. apiDownload 쿠폰은 플레이어가 API를 직접 호출하므로 호출하지 않음couponClick
sauceflexCouponAndroidScheme
sauceflexCouponIosScheme
sauceflexMoveCoupon 값 · schemeUrlcouponClick
sauceflexMoveRewardbroadcastIdx · linkUrlrewardClick
sauceflexOnSharelinkUrl · shortUrl · broadcastIdx · broadcastThumbnailUrl · broadcastNameshareClick
sauceflexMoveExit없음closeClick
sauceflexPictureInPicture없음. PIP 창은 앱이 구현pipClick
sauceflexTurnOnNotification
sauceflexTurnOffNotification
accessToken · broadcastId · broadcastUrl · memberId · partnerUniqueId · programmingStartDt · programmingEndDtnotificationRequest
sauceflexSendAppsFlyerEventevent · params없음
🟣 앱 → 플레이어: 앱이 플레이어로 보내는 이름

앱이 웹뷰에서 window.postMessage(JSON.stringify({ key, params }), '*')로 보내는 key와 params입니다.

이름값자사몰 페이지에서는
sauceflexEnterAsGuest없음enterAsGuest. sauceflexEnter를 받은 직후에만 반영
sauceflexTurnOnNotificationCallback
sauceflexTurnOffNotificationCallback
broadcastId · result('success' · 'fail' · 'cancel'). 보내지 않으면 알림 버튼이 잠긴 채 남음respondToNotification
sauceflexPlay
sauceflexPause
sauceflexPlayLive
없음play · pause · playLive
sauceflexFloatingModeMuteOn
sauceflexFloatingModeMuteOff
없음mute · unmute
sauceflexFocusBackelementId · delayMsecrestoreFocus
sauceflexOpenCustomToast문구(문자열)showToast
sauceFlexPIPtrue PIP 시작 · false PIP 해제없음
sauceflexWebviewReloading없음없음. Android에서 재생을 다시 시작

Did this page help you?
🏠 소스라이브 🎬 소스클립 🔗 소스링크 📢 소스애드
🧩 API 가이드
🆕 최근 업데이트
💬 도움이 더 필요하신가요?
메일로 문의 카카오톡 채널로 문의
담당자에게 문의하기

궁금한 점이나 불편했던 점을 남겨주시면 담당자가 확인 후 답변드릴게요.

가이드 챗봇
* AI를 활용해 답변해서 사실과 다를 수도 있어요. 더 궁금한 사항은 '담당자에게 문의하기'를 이용해주세요.
💡 궁금한 솔루션(예: 라이브, 링크 등)을 함께 적어주시면 더 정확한 답변을 받을 수 있어요.