브릿지 이벤트 레퍼런스
소스라이브 플레이어가 발생시키는 모든 브릿지 이벤트의 key와 params 구조를 정리합니다. 웹 환경에서는 window.postMessage 리스너의 jsonData.key로, Android에서는 @JavascriptInterface로, iOS에서는 WKScriptMessageHandler로 동일한 이벤트를 수신합니다.
목차
🔵 라이프사이클
🟠 사용자 액션
🟣 앱스킴 (WebView 전용)
sauceflexBannerAndroidScheme배너 · Android
sauceflexBannerIosScheme배너 · iOS
sauceflexProductAndroidScheme상품 · Android
sauceflexProductIosScheme상품 · iOS
sauceflexSlotBannerAndroidScheme슬롯 배너 · Android
sauceflexSlotBannerIosScheme슬롯 배너 · iOS
sauceflexCouponAndroidScheme쿠폰 · Android
sauceflexCouponIosScheme쿠폰 · iOS
🔵 라이프사이클 이벤트 — 사용자 액션 없이 플레이어가 자동 전송
sauceflexEnter
페이지 진입 시 자동
방송 페이지에 진입하면 자동으로 호출됩니다. 시청자의 방송 입장 시점을 감지하는 데 활용합니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| params 없음 (Void) | |||
sauceflexBroadcastStatus
방송 상태 변경 시 자동
방송 상태가 변경될 때마다 자동으로 호출됩니다.
broadcastStateCode를 통해 현재 방송 상태를 파악할 수 있습니다.| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| broadcastStateCode | BroadcastStateCode | 필수 | 현재 방송 상태 코드. 가능한 값은 어드민 문서를 참고하세요. |
sauceflexSendPlayTime
재생 위치 변경 시 자동
라이브 또는 VOD의 재생 위치가 변경될 때마다 지속적으로 전송됩니다. 시청 시간 추적 등에 활용합니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| position | Number | 필수 | 현재 영상 재생 위치 (초 단위) |
sauceflexFirstPlay
첫 재생 시 자동
시청자가 방송에 입장한 후 영상이 최초로 재생될 때 한 번 전송됩니다. 첫 재생 시점 기록이나 온보딩 UI 표시 등에 활용합니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| params 없음 (Void) | |||
sauceflexUpdatePvCount
PV 수 변경 시 자동
방송의 PV(Page View) 수가 업데이트될 때마다 전송됩니다. 현재 시청자 수를 자사몰 UI에 표시하는 데 활용합니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| pvCount | Number | null | 선택 | 현재 PV 수. 집계 중이거나 비공개인 경우 null |
sauceflexPlayerMuteStatus
음소거 상태 변경 시 자동
플레이어의 음소거 상태가 변경될 때마다 전송됩니다. 자사몰에서 음소거 상태에 따라 별도 UI를 제어할 때 활용합니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| isMute | Boolean | 필수 | 음소거 여부. true: 음소거 / false: 소리 켜짐 |
🟠 사용자 액션 이벤트 — 시청자가 특정 UI를 클릭할 때 전송
sauceflexMoveExit
나가기 버튼 클릭
방송 나가기 버튼을 클릭할 때 호출됩니다. 이전 페이지로 이동하거나 플레이어를 닫는 처리에 활용합니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| params 없음 (Void) | |||
sauceflexMoveLogin
로그인 버튼 클릭
게스트가 채팅·쿠폰 등 로그인이 필요한 기능에 접근할 때 로그인 버튼을 클릭하면 호출됩니다. 자세한 구현은 로그인 연동 가이드를 참고하세요.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| params 없음 (Void) | |||
sauceflexMoveProduct
상품 클릭
플레이어 내 상품을 클릭할 때 전송됩니다. 자세한 구현은 상품 클릭 연동 가이드를 참고하세요.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| linkUrl | String | 필수 | 상품 페이지 링크 URL |
| broadcastIdx | String | 필수 | 라이브 ID |
| price | String | Number | 필수 | 상품 가격 |
| externalProductId | String | null | 선택 | 자사몰에서 등록한 상품 코드 |
| isSoldout | Boolean | 필수 | 품절 여부 |
sauceflexMoveCart
장바구니 버튼 클릭
플레이어 내 상품의 장바구니 버튼을 클릭할 때 전송됩니다.
externalProductId로 자사몰 상품을 식별하고 장바구니 담기 처리를 수행합니다.| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| externalProductId | String | null | 선택 | 자사몰에서 등록한 상품 코드. 등록되지 않은 경우 null |
sauceflexMoveBanner
배너 클릭
플레이어 내 배너를 클릭할 때 전송됩니다. 배너 링크로 이동하거나 커스텀 동작을 정의하세요.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| linkUrl | String | 필수 | 배너에 설정된 링크 URL |
| broadcastIdx | String | 필수 | 라이브 ID |
| bannerId | String | 필수 | 배너 ID |
sauceflexMoveSlotBanner
슬롯 배너 클릭
슬롯 배너를 클릭할 때 전송됩니다.
webUrlTargetTypeCode로 현재 창 또는 새 창 여부를 구분하세요.| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| slotBannerId | String | 필수 | 슬롯 배너 ID |
| broadcastId | String | 필수 | 라이브 ID |
| url | String | 필수 | 이동할 Web URL 링크 |
| webUrlTargetTypeCode | "BLANK" | "SELF" | 필수 | "BLANK": 새 창 / "SELF": 현재 창 |
sauceflexPictureInPicture
PIP 버튼 클릭 (WebView 전용)
PIP(Picture-in-Picture) 버튼 클릭 시 전송됩니다. 클릭 시 플레이어 내 버튼 UI가 자동으로 숨김 처리됩니다. PIP 기능 자체는 자사몰에서 별도 개발이 필요합니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| params 없음 (Void) | |||
sauceflexMoveCoupon
쿠폰 버튼 클릭
쿠폰 버튼 클릭 시 전송됩니다.
couponType으로 처리 방식을 구분합니다. 자세한 구현은 쿠폰 연동 가이드를 참고하세요.| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| broadcastIdx | String | 필수 | 라이브 ID |
| couponType | 'link' | 'newWindow' | 'download' | 'custom' | 'apiDownload' | 필수 | 어드민에서 설정한 쿠폰 클릭 이벤트 유형 |
| couponCode | String | null | 선택 | 쿠폰 코드 |
| couponId | String | null | 선택 | 등록된 쿠폰 ID |
| couponName | String | null | 선택 | 등록된 쿠폰명 |
| linkUrl | String | null | 선택 | 링크 이동 URL |
| metaData | String | null | 선택 | 사용자 정의 데이터 (JSON 문자열) |
sauceflexMoveReward
리워드 CLICK 버튼 클릭
리워드 달성 후 CLICK 버튼을 클릭할 때 전송됩니다. 자세한 구현은 리워드 연동 가이드를 참고하세요.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| broadcastIdx | String | 필수 | 라이브 ID |
| linkUrl | String | 필수 | 라이브콘솔에서 설정한 리워드 연결 URL |
🟣 앱스킴 이벤트 — WebView 환경에서 앱 전용 링크(앱스킴) 사용 시
⚠️ 앱스킴 이벤트는 네이티브 앱의 WebView 환경에서만 발생합니다. 어드민에서 해당 배너·상품·쿠폰에 앱스킴 URL이 설정된 경우에 전송되며, 앱 전용 링크 처리에 실패할 경우
webUrl로 폴백합니다.
sauceflexBannerAndroidScheme
배너 클릭 · Android
배너 클릭 시 Android 앱 전용 링크(앱스킴)가 설정된 경우 전송됩니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| url | String | 필수 | Android 앱 전용 링크 (앱스킴 URL) |
| broadcastIdx | String | 필수 | 라이브 ID |
| bannerId | String | 필수 | 배너 ID |
| webUrl | String | null | 선택 | 앱스킴 실패 시 Fallback Web URL |
sauceflexBannerIosScheme
배너 클릭 · iOS
배너 클릭 시 iOS 앱 전용 링크(앱스킴)가 설정된 경우 전송됩니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| url | String | 필수 | iOS 앱 전용 링크 (앱스킴 URL) |
| broadcastIdx | String | 필수 | 라이브 ID |
| bannerId | String | 필수 | 배너 ID |
| webUrl | String | null | 선택 | 앱스킴 실패 시 Fallback Web URL |
sauceflexProductAndroidScheme
상품 클릭 · Android
상품 클릭 시 Android 앱 전용 링크(앱스킴)가 설정된 경우 전송됩니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| url | String | 필수 | Android 앱 전용 링크 |
| broadcastIdx | String | 필수 | 라이브 ID |
| price | String | Number | 필수 | 상품 가격 |
| externalProductId | String | null | 선택 | 상품 코드 |
| isSoldout | Boolean | 필수 | 품절 여부 |
| webUrl | String | null | 선택 | 앱스킴 실패 시 Fallback Web URL |
sauceflexProductIosScheme
상품 클릭 · iOS
상품 클릭 시 iOS 앱 전용 링크(앱스킴)가 설정된 경우 전송됩니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| url | String | 필수 | iOS 앱 전용 링크 |
| broadcastIdx | String | 필수 | 라이브 ID |
| price | String | Number | 필수 | 상품 가격 |
| externalProductId | String | null | 선택 | 상품 코드 |
| isSoldout | Boolean | 필수 | 품절 여부 |
| webUrl | String | null | 선택 | 앱스킴 실패 시 Fallback Web URL |
sauceflexSlotBannerAndroidScheme
슬롯 배너 클릭 · Android
슬롯 배너 클릭 시 Android 앱 전용 링크(앱스킴)가 설정된 경우 전송됩니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| slotBannerId | String | 필수 | 슬롯 배너 ID |
| broadcastId | String | 필수 | 라이브 ID |
| url | String | 필수 | 앱스킴 URL |
| webUrlTargetTypeCode | "BLANK" | "SELF" | 필수 | 새 창 / 현재 창 |
| webUrl | String | 필수 | Fallback Web URL |
sauceflexSlotBannerIosScheme
슬롯 배너 클릭 · iOS
슬롯 배너 클릭 시 iOS 앱 전용 링크(앱스킴)가 설정된 경우 전송됩니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| slotBannerId | String | 필수 | 슬롯 배너 ID |
| broadcastId | String | 필수 | 라이브 ID |
| url | String | 필수 | 앱스킴 URL |
| webUrlTargetTypeCode | "BLANK" | "SELF" | 필수 | 새 창 / 현재 창 |
| webUrl | String | 필수 | Fallback Web URL |
sauceflexCouponAndroidScheme
쿠폰 버튼 클릭 · Android
쿠폰 버튼 클릭 시 Android 앱 전용 링크(앱스킴)가 설정된 경우 전송됩니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| broadcastIdx | String | 필수 | 라이브 ID |
| couponType | 'link' | 'newWindow' | 'download' | 'custom' | 'apiDownload' | 필수 | 쿠폰 클릭 이벤트 유형 |
| couponCode | String | null | 선택 | 쿠폰 코드 |
| couponId | String | null | 선택 | 등록된 쿠폰 ID |
| couponName | String | null | 선택 | 등록된 쿠폰명 |
| linkUrl | String | null | 선택 | 링크 이동 URL |
| metaData | String | null | 선택 | 사용자 정의 데이터 (JSON 문자열) |
| schemeUrl | String | null | 선택 | 앱스킴 URL |
sauceflexCouponIosScheme
쿠폰 버튼 클릭 · iOS
쿠폰 버튼 클릭 시 iOS 앱 전용 링크(앱스킴)가 설정된 경우 전송됩니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| broadcastIdx | String | 필수 | 라이브 ID |
| couponType | 'link' | 'newWindow' | 'download' | 'custom' | 'apiDownload' | 필수 | 쿠폰 클릭 이벤트 유형 |
| couponCode | String | null | 선택 | 쿠폰 코드 |
| couponId | String | null | 선택 | 등록된 쿠폰 ID |
| couponName | String | null | 선택 | 등록된 쿠폰명 |
| linkUrl | String | null | 선택 | 링크 이동 URL |
| metaData | String | null | 선택 | 사용자 정의 데이터 (JSON 문자열) |
| schemeUrl | String | null | 선택 | 앱스킴 URL |
🟢 알림 · 포커스 제어 이벤트 — 라이브 알림 버튼과 포커스 복구
📌 알림 받기/해제(
sauceflexTurnOnNotification · sauceflexTurnOffNotification)는 사용자가 라이브 예고 플레이어의 알림 버튼을 누를 때 플레이어가 전송합니다. 고객사는 알림 처리 후 콜백(...NotificationCallback)을 플레이어로 다시 전송해야 버튼 상태가 갱신됩니다. 전체 흐름은 라이브 알림 버튼 연동 가이드를 참고하세요.
sauceflexFocusBack
포커스 복구 (고객사 → 플레이어)
고객사 페이지에서 특정 UI 동작(예: 공유하기 시트) 이후 라이브 플레이어 내부로 포커스를 복구할 때 고객사가 플레이어로 전송하는 이벤트입니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| elementId | 'share-bottom-sheet' | 필수 | 포커스를 복구할 대상의 매핑 ID. 'share-bottom-sheet': 공유하기 버튼으로 복구 |
| delayMsec | Number | null | 선택 | 포커스 복구까지 지연 시간(ms). null이면 즉시 복구 |
sauceflexTurnOnNotification
알림 받기 클릭
라이브 예고 플레이어에서 사용자가 알림 받기를 클릭할 때 전송됩니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| broadcastId | String | 필수 | 라이브 ID |
| broadcastUrl | String | 필수 | 라이브 플레이어 링크 |
| memberId | String | 필수 | 유저 식별 ID |
| partnerUniqueId | String | 필수 | 파트너 ID |
| programmingStartDt | String | 필수 | 라이브 시작 예정 시간 (YYYY-MM-DDThh:mm:ss.sssZ · UTC) |
| programmingEndDt | String | 필수 | 라이브 종료 예정 시간 (YYYY-MM-DDThh:mm:ss.sssZ · UTC) |
sauceflexTurnOffNotification
알림 해제 클릭
라이브 예고 플레이어에서 사용자가 알림 해제를 클릭할 때 전송됩니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| broadcastId | String | 필수 | 라이브 ID |
| broadcastUrl | String | 필수 | 라이브 플레이어 링크 |
| memberId | String | 필수 | 유저 식별 ID |
| partnerUniqueId | String | 필수 | 파트너 ID |
| programmingStartDt | String | 필수 | 라이브 시작 예정 시간 (YYYY-MM-DDThh:mm:ss.sssZ · UTC) |
| programmingEndDt | String | 필수 | 라이브 종료 예정 시간 (YYYY-MM-DDThh:mm:ss.sssZ · UTC) |
sauceflexTurnOnNotificationCallback
알림 받기 성공 콜백 (고객사 → 플레이어)
고객사 측 알림 받기 처리가 성공하면 고객사가 플레이어로 전송합니다. 수신 시 플레이어가 알림 버튼 상태를 갱신합니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| broadcastId | String | 필수 | 라이브 ID |
sauceflexTurnOffNotificationCallback
알림 해제 성공 콜백 (고객사 → 플레이어)
고객사 측 알림 해제 처리가 성공하면 고객사가 플레이어로 전송합니다. 수신 시 플레이어가 알림 버튼 상태를 갱신합니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| broadcastId | String | 필수 | 라이브 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 } })
Updated 1 day ago