GuidesAPI GuideChangelog
Log In
Guides

브릿지 이벤트 레퍼런스

소스라이브 플레이어가 발생시키는 모든 브릿지 이벤트의 keyparams 구조를 정리합니다. 웹 환경에서는 window.postMessage 리스너의 jsonData.key로, Android에서는 @JavascriptInterface로, iOS에서는 WKScriptMessageHandler로 동일한 이벤트를 수신합니다.

브릿지 이벤트 레퍼런스 — 소스라이브 플레이어
📖 참조 문서
📋 사전조건: 브릿지 이벤트 연동 완료
🔵 라이프사이클 이벤트 — 사용자 액션 없이 플레이어가 자동 전송
sauceflexEnter 페이지 진입 시 자동
방송 페이지에 진입하면 자동으로 호출됩니다. 시청자의 방송 입장 시점을 감지하는 데 활용합니다.
필드타입필수설명
params 없음 (Void)
sauceflexBroadcastStatus 방송 상태 변경 시 자동
방송 상태가 변경될 때마다 자동으로 호출됩니다. broadcastStateCode를 통해 현재 방송 상태를 파악할 수 있습니다.
필드타입필수설명
broadcastStateCodeBroadcastStateCode필수현재 방송 상태 코드. 가능한 값은 어드민 문서를 참고하세요.
sauceflexSendPlayTime 재생 위치 변경 시 자동
라이브 또는 VOD의 재생 위치가 변경될 때마다 지속적으로 전송됩니다. 시청 시간 추적 등에 활용합니다.
필드타입필수설명
positionNumber필수현재 영상 재생 위치 (초 단위)
sauceflexFirstPlay 첫 재생 시 자동
시청자가 방송에 입장한 후 영상이 최초로 재생될 때 한 번 전송됩니다. 첫 재생 시점 기록이나 온보딩 UI 표시 등에 활용합니다.
필드타입필수설명
params 없음 (Void)
sauceflexUpdatePvCount PV 수 변경 시 자동
방송의 PV(Page View) 수가 업데이트될 때마다 전송됩니다. 현재 시청자 수를 자사몰 UI에 표시하는 데 활용합니다.
필드타입필수설명
pvCountNumber | null선택현재 PV 수. 집계 중이거나 비공개인 경우 null
sauceflexPlayerMuteStatus 음소거 상태 변경 시 자동
플레이어의 음소거 상태가 변경될 때마다 전송됩니다. 자사몰에서 음소거 상태에 따라 별도 UI를 제어할 때 활용합니다.
필드타입필수설명
isMuteBoolean필수음소거 여부. true: 음소거 / false: 소리 켜짐
🟠 사용자 액션 이벤트 — 시청자가 특정 UI를 클릭할 때 전송
sauceflexMoveExit 나가기 버튼 클릭
방송 나가기 버튼을 클릭할 때 호출됩니다. 이전 페이지로 이동하거나 플레이어를 닫는 처리에 활용합니다.
필드타입필수설명
params 없음 (Void)
sauceflexMoveLogin 로그인 버튼 클릭
게스트가 채팅·쿠폰 등 로그인이 필요한 기능에 접근할 때 로그인 버튼을 클릭하면 호출됩니다. 로그인이 요청된 라이브·상점 정보가 함께 전달됩니다. 자세한 구현은 로그인 연동 가이드를 참고하세요.
필드타입필수설명
broadcastIdString필수로그인이 요청된 라이브 ID
shopIdString필수라이브를 진행 중인 상점 ID
shopNameString필수라이브를 진행 중인 상점 이름
sauceflexMoveProduct 상품 클릭
플레이어 내 상품을 클릭할 때 전송됩니다. 자세한 구현은 상품 클릭 연동 가이드를 참고하세요.
필드타입필수설명
linkUrlString필수상품 페이지 링크 URL
broadcastIdxString필수라이브 ID
priceString | Number필수상품 가격
externalProductIdString | null선택자사몰에서 등록한 상품 코드
isSoldoutBoolean필수품절 여부
sauceflexMoveCart 장바구니 버튼 클릭
플레이어 내 상품의 장바구니 버튼을 클릭할 때 전송됩니다. externalProductId로 자사몰 상품을 식별하고 장바구니 담기 처리를 수행합니다.
필드타입필수설명
externalProductIdString | null선택자사몰에서 등록한 상품 코드. 등록되지 않은 경우 null
sauceflexMoveBanner 배너 클릭
플레이어 내 배너를 클릭할 때 전송됩니다. 배너 링크로 이동하거나 커스텀 동작을 정의하세요.
필드타입필수설명
linkUrlString필수배너에 설정된 링크 URL
broadcastIdxString필수라이브 ID
bannerIdString필수배너 ID
sauceflexMoveSlotBanner 슬롯 배너 클릭
슬롯 배너를 클릭할 때 전송됩니다. webUrlTargetTypeCode로 현재 창 또는 새 창 여부를 구분하세요.
필드타입필수설명
slotBannerIdString필수슬롯 배너 ID
broadcastIdString필수라이브 ID
urlString필수이동할 Web URL 링크
webUrlTargetTypeCode"BLANK" | "SELF"필수"BLANK": 새 창 / "SELF": 현재 창
sauceflexOnShare 공유하기 버튼 클릭
공유하기 버튼 클릭 시 전송됩니다. 공유 URL과 방송 정보를 활용하여 자사몰의 공유 기능을 구현하세요.
필드타입필수설명
linkUrlString필수방송 공유 링크 URL
shortUrlString | null선택방송 단축 링크
broadcastIdxString필수라이브 ID
broadcastThumbnailUrlString필수방송 썸네일 이미지 URL
broadcastNameString필수방송명
sauceflexPictureInPicture PIP 버튼 클릭 (WebView 전용)
PIP(Picture-in-Picture) 버튼 클릭 시 전송됩니다. 클릭 시 플레이어 내 버튼 UI가 자동으로 숨김 처리됩니다. PIP 기능 자체는 자사몰에서 별도 개발이 필요합니다.
필드타입필수설명
params 없음 (Void)
sauceflexMoveCoupon 쿠폰 버튼 클릭
쿠폰 버튼 클릭 시 전송됩니다. couponType으로 처리 방식을 구분합니다. 자세한 구현은 쿠폰 연동 가이드를 참고하세요.
필드타입필수설명
broadcastIdxString필수라이브 ID
couponType'link' | 'newWindow' | 'download' | 'custom' | 'apiDownload'필수어드민에서 설정한 쿠폰 클릭 이벤트 유형
couponCodeString | null선택쿠폰 코드
couponIdString | null선택등록된 쿠폰 ID
couponNameString | null선택등록된 쿠폰명
linkUrlString | null선택링크 이동 URL
metaDataString | null선택사용자 정의 데이터 (JSON 문자열)
sauceflexMoveReward 리워드 CLICK 버튼 클릭
리워드 달성 후 CLICK 버튼을 클릭할 때 전송됩니다. 자세한 구현은 리워드 연동 가이드를 참고하세요.
필드타입필수설명
broadcastIdxString필수라이브 ID
linkUrlString필수라이브콘솔에서 설정한 리워드 연결 URL
🟣 앱스킴 이벤트 — WebView 환경에서 앱 전용 링크(앱스킴) 사용 시
⚠️ 앱스킴 이벤트는 네이티브 앱의 WebView 환경에서만 발생합니다. 어드민에서 해당 배너·상품·쿠폰에 앱스킴 URL이 설정된 경우에 전송되며, 앱 전용 링크 처리에 실패할 경우 webUrl로 폴백합니다.
sauceflexBannerAndroidScheme 배너 클릭 · Android
배너 클릭 시 Android 앱 전용 링크(앱스킴)가 설정된 경우 전송됩니다.
필드타입필수설명
urlString필수Android 앱 전용 링크 (앱스킴 URL)
broadcastIdxString필수라이브 ID
bannerIdString필수배너 ID
webUrlString | null선택앱스킴 실패 시 Fallback Web URL
sauceflexBannerIosScheme 배너 클릭 · iOS
배너 클릭 시 iOS 앱 전용 링크(앱스킴)가 설정된 경우 전송됩니다.
필드타입필수설명
urlString필수iOS 앱 전용 링크 (앱스킴 URL)
broadcastIdxString필수라이브 ID
bannerIdString필수배너 ID
webUrlString | null선택앱스킴 실패 시 Fallback Web URL
sauceflexProductAndroidScheme 상품 클릭 · Android
상품 클릭 시 Android 앱 전용 링크(앱스킴)가 설정된 경우 전송됩니다.
필드타입필수설명
urlString필수Android 앱 전용 링크
broadcastIdxString필수라이브 ID
priceString | Number필수상품 가격
externalProductIdString | null선택상품 코드
isSoldoutBoolean필수품절 여부
webUrlString | null선택앱스킴 실패 시 Fallback Web URL
sauceflexProductIosScheme 상품 클릭 · iOS
상품 클릭 시 iOS 앱 전용 링크(앱스킴)가 설정된 경우 전송됩니다.
필드타입필수설명
urlString필수iOS 앱 전용 링크
broadcastIdxString필수라이브 ID
priceString | Number필수상품 가격
externalProductIdString | null선택상품 코드
isSoldoutBoolean필수품절 여부
webUrlString | null선택앱스킴 실패 시 Fallback Web URL
sauceflexSlotBannerAndroidScheme 슬롯 배너 클릭 · Android
슬롯 배너 클릭 시 Android 앱 전용 링크(앱스킴)가 설정된 경우 전송됩니다.
필드타입필수설명
slotBannerIdString필수슬롯 배너 ID
broadcastIdString필수라이브 ID
urlString필수앱스킴 URL
webUrlTargetTypeCode"BLANK" | "SELF"필수새 창 / 현재 창
webUrlString필수Fallback Web URL
sauceflexSlotBannerIosScheme 슬롯 배너 클릭 · iOS
슬롯 배너 클릭 시 iOS 앱 전용 링크(앱스킴)가 설정된 경우 전송됩니다.
필드타입필수설명
slotBannerIdString필수슬롯 배너 ID
broadcastIdString필수라이브 ID
urlString필수앱스킴 URL
webUrlTargetTypeCode"BLANK" | "SELF"필수새 창 / 현재 창
webUrlString필수Fallback Web URL
sauceflexCouponAndroidScheme 쿠폰 버튼 클릭 · Android
쿠폰 버튼 클릭 시 Android 앱 전용 링크(앱스킴)가 설정된 경우 전송됩니다.
필드타입필수설명
broadcastIdxString필수라이브 ID
couponType'link' | 'newWindow' | 'download' | 'custom' | 'apiDownload'필수쿠폰 클릭 이벤트 유형
couponCodeString | null선택쿠폰 코드
couponIdString | null선택등록된 쿠폰 ID
couponNameString | null선택등록된 쿠폰명
linkUrlString | null선택링크 이동 URL
metaDataString | null선택사용자 정의 데이터 (JSON 문자열)
schemeUrlString | null선택앱스킴 URL
sauceflexCouponIosScheme 쿠폰 버튼 클릭 · iOS
쿠폰 버튼 클릭 시 iOS 앱 전용 링크(앱스킴)가 설정된 경우 전송됩니다.
필드타입필수설명
broadcastIdxString필수라이브 ID
couponType'link' | 'newWindow' | 'download' | 'custom' | 'apiDownload'필수쿠폰 클릭 이벤트 유형
couponCodeString | null선택쿠폰 코드
couponIdString | null선택등록된 쿠폰 ID
couponNameString | null선택등록된 쿠폰명
linkUrlString | null선택링크 이동 URL
metaDataString | null선택사용자 정의 데이터 (JSON 문자열)
schemeUrlString | null선택앱스킴 URL
🟢 알림 · 포커스 제어 이벤트 — 라이브 알림 버튼과 포커스 복구
📌 알림 받기/해제(sauceflexTurnOnNotification · sauceflexTurnOffNotification)는 사용자가 라이브 예고 플레이어의 알림 버튼을 누를 때 플레이어가 전송합니다. 고객사는 알림 처리 후 콜백(...NotificationCallback)을 플레이어로 다시 전송해야 버튼 상태가 갱신됩니다. 전체 흐름은 라이브 알림 버튼 연동 가이드를 참고하세요.
sauceflexFocusBack 포커스 복구 (고객사 → 플레이어)
고객사 페이지에서 특정 UI 동작(예: 공유하기 시트) 이후 라이브 플레이어 내부로 포커스를 복구할 때 고객사가 플레이어로 전송하는 이벤트입니다.
필드타입필수설명
elementId'share-bottom-sheet'필수포커스를 복구할 대상의 매핑 ID. 'share-bottom-sheet': 공유하기 버튼으로 복구
delayMsecNumber | null선택포커스 복구까지 지연 시간(ms). null이면 즉시 복구
sauceflexTurnOnNotification 알림 받기 클릭
라이브 예고 플레이어에서 사용자가 알림 받기를 클릭할 때 전송됩니다.
필드타입필수설명
broadcastIdString필수라이브 ID
broadcastUrlString필수라이브 플레이어 링크
memberIdString필수유저 식별 ID
partnerUniqueIdString필수파트너 ID
programmingStartDtString필수라이브 시작 예정 시간 (YYYY-MM-DDThh:mm:ss.sssZ · UTC)
programmingEndDtString필수라이브 종료 예정 시간 (YYYY-MM-DDThh:mm:ss.sssZ · UTC)
sauceflexTurnOffNotification 알림 해제 클릭
라이브 예고 플레이어에서 사용자가 알림 해제를 클릭할 때 전송됩니다.
필드타입필수설명
broadcastIdString필수라이브 ID
broadcastUrlString필수라이브 플레이어 링크
memberIdString필수유저 식별 ID
partnerUniqueIdString필수파트너 ID
programmingStartDtString필수라이브 시작 예정 시간 (YYYY-MM-DDThh:mm:ss.sssZ · UTC)
programmingEndDtString필수라이브 종료 예정 시간 (YYYY-MM-DDThh:mm:ss.sssZ · UTC)
sauceflexTurnOnNotificationCallback 알림 받기 성공 콜백 (고객사 → 플레이어)
고객사 측 알림 받기 처리가 성공하면 고객사가 플레이어로 전송합니다. 수신 시 플레이어가 알림 버튼 상태를 갱신합니다.
필드타입필수설명
broadcastIdString필수라이브 ID
sauceflexTurnOffNotificationCallback 알림 해제 성공 콜백 (고객사 → 플레이어)
고객사 측 알림 해제 처리가 성공하면 고객사가 플레이어로 전송합니다. 수신 시 플레이어가 알림 버튼 상태를 갱신합니다.
필드타입필수설명
broadcastIdString필수라이브 ID
전체 이벤트 리스너 예시

모든 이벤트를 console.log로 확인하는 디버깅용 전체 리스너입니다. 개발 초기 단계에 활용하세요.

JavaScript — 전체 이벤트 디버깅 리스너
window.addEventListener('message', (e) => {
  if (typeof e.data !== 'string') return
  const { key, params } = JSON.parse(e.data)

  switch (key) {
    // ── 라이프사이클 ───────────────────
    case 'sauceflexEnter':
      console.log('방송 입장'); break
    case 'sauceflexBroadcastStatus':
      console.log('방송 상태', params.broadcastStateCode); break
    case 'sauceflexSendPlayTime':
      console.log('재생 위치', params.position); break
    case 'sauceflexFirstPlay':
      console.log('첫 재생'); break
    case 'sauceflexUpdatePvCount':
      console.log('PV 수', params.pvCount); break
    case 'sauceflexPlayerMuteStatus':
      console.log('음소거', params.isMute); break

    // ── 사용자 액션 ────────────────────
    case 'sauceflexMoveExit':
      console.log('나가기'); break
    case 'sauceflexMoveLogin':
      console.log('로그인 클릭', params.broadcastId, params.shopId); break
    case 'sauceflexMoveProduct':
      console.log('상품 클릭', params.linkUrl, params.externalProductId); break
    case 'sauceflexMoveCart':
      console.log('장바구니 클릭', params.externalProductId); break
    case 'sauceflexMoveBanner':
      console.log('배너 클릭', params.linkUrl, params.bannerId); break
    case 'sauceflexMoveSlotBanner':
      console.log('슬롯 배너 클릭', params.url); break
    case 'sauceflexOnShare':
      console.log('공유', params.linkUrl, params.shortUrl); break
    case 'sauceflexPictureInPicture':
      console.log('PIP'); break
    case 'sauceflexMoveCoupon':
      console.log('쿠폰', params.couponType, params.couponCode); break
    case 'sauceflexMoveReward':
      console.log('리워드', params.linkUrl); break

    // ── 앱스킴 (WebView 전용) ──────────
    case 'sauceflexBannerAndroidScheme':
    case 'sauceflexBannerIosScheme':
      console.log('배너 앱스킴', params.url); break
    case 'sauceflexProductAndroidScheme':
    case 'sauceflexProductIosScheme':
      console.log('상품 앱스킴', params.url); break
    case 'sauceflexSlotBannerAndroidScheme':
    case 'sauceflexSlotBannerIosScheme':
      console.log('슬롯 배너 앱스킴', params.url); break
    case 'sauceflexCouponAndroidScheme':
    case 'sauceflexCouponIosScheme':
      console.log('쿠폰 앱스킴', params.schemeUrl); break

    // ── 라이브 알림 (예고 플레이어) ─────
    case 'sauceflexTurnOnNotification':
      console.log('알림 받기', params.broadcastId); break
    case 'sauceflexTurnOffNotification':
      console.log('알림 해제', params.broadcastId); break
  }
})

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

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

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