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 로그인 버튼 클릭
게스트가 채팅·쿠폰 등 로그인이 필요한 기능에 접근할 때 로그인 버튼을 클릭하면 호출됩니다. 자세한 구현은 로그인 연동 가이드를 참고하세요.
필드타입필수설명
params 없음 (Void)
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('로그인 클릭'); 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
  }
})


bot에 문의하기