브릿지 이벤트 연동
소스라이브 플레이어와 자사몰·네이티브 앱 사이의 양방향 이벤트 통신 구조입니다. 상품 클릭, 쿠폰 다운로드, 로그인 요청 등 플레이어 내 이벤트가 발생하면 자사몰에서 직접 처리할 수 있습니다. 브릿지 이벤트는 실행 환경(웹·Android·iOS)을 자동 감지하여 적합한 방식으로 이벤트를 전달합니다.
브릿지 이벤트 동작 원리
플레이어에서 이벤트가 발생하면 실행 환경을 자동으로 감지하여 아래 세 가지 방식 중 하나로 전달합니다. 자사몰 또는 네이티브 앱은 해당 환경에 맞는 방식으로 수신 처리를 구현하면 됩니다.
소스라이브 플레이어
이벤트 발생
상품 클릭, 쿠폰 다운로드, 로그인 버튼 클릭, 리워드 달성 등의 액션 발생 시 브릿지 이벤트를 통해 전달합니다.
환경 자동 감지
웹
postMessage / addEventListener
Android
window.sauceflex[key]()
iOS
webkit.messageHandlers[key]
→
자사몰 / 네이티브 앱
이벤트 처리
등록한 리스너 또는 인터페이스에서 이벤트를 수신하고, 페이지 이동·API 호출 등 원하는 동작을 수행합니다.
⚡ 환경별 수신 데이터 구조가 다릅니다. 웹 환경은
{"{ key, params }"} 형태의 JSON 문자열을 수신하며 key로 이벤트를 구분합니다. Android·iOS 네이티브 환경은 params만 JSON 문자열로 수신하며, 호출된 메서드·핸들러 이름 자체가 이벤트 key 역할을 합니다.
적용 방법
실행 환경에 맞는 탭을 선택하세요. 구현해야 할 이벤트만 추가하면 됩니다.
JavaScript
window.addEventListener('message', (e) => { // 데이터가 문자열인 경우에만 처리 if (typeof e.data !== 'string') return const { key, params } = JSON.parse(e.data) switch (key) { case 'sauceflexMoveProduct': window.location.href = params.linkUrl break case 'sauceflexMoveLogin': window.location.href = '/login' break // 필요한 이벤트를 추가하세요 } })
💡 이벤트 데이터 검증:
typeof e.data !== 'string' 조건으로 다른 출처의 메시지를 걸러내세요. 브라우저 확장 프로그램 등에서도 message 이벤트가 발생할 수 있습니다.
Kotlin — JavascriptInterface 정의
// 1. JavascriptInterface 클래스 정의 class SauceflexBridge { // params가 있는 이벤트 — JSON 문자열로 수신 @JavascriptInterface fun sauceflexMoveProduct(payload: String?) { val params = JSONObject(payload ?: return) val linkUrl = params.getString("linkUrl") // 상품 페이지로 이동 } // params가 없는 이벤트 — 인자 없이 호출됨 @JavascriptInterface fun sauceflexMoveLogin() { // 로그인 페이지로 이동 } // 필요한 이벤트를 추가하세요 }
Kotlin — WebView에 등록
// 2. WebView에 "sauceflex" 이름으로 등록 webView.settings.javaScriptEnabled = true webView.addJavascriptInterface(SauceflexBridge(), "sauceflex")
💡 이벤트 이름(예:
sauceflexMoveProduct)이 메서드 이름과 동일합니다. 등록 이름은 반드시 "sauceflex"로 고정해야 합니다.
Swift — WKWebView 설정
// 1. 이벤트별 message handler 등록 let config = WKWebViewConfiguration() let contentController = WKUserContentController() contentController.add(self, name: "sauceflexMoveProduct") contentController.add(self, name: "sauceflexMoveLogin") // 필요한 이벤트를 추가하세요 config.userContentController = contentController let webView = WKWebView(frame: .zero, configuration: config)
Swift — WKScriptMessageHandler 구현
// 2. 이벤트 수신 처리 extension ViewController: WKScriptMessageHandler { func userContentController( _ userContentController: WKUserContentController, didReceive message: WKScriptMessage ) { // params가 없는 이벤트는 body가 null if let payload = message.body as? String, let data = payload.data(using: .utf8), let params = try? JSONSerialization.jsonObject(with: data) as? [String: Any] { // params가 있는 이벤트 switch message.name { case "sauceflexMoveProduct": let linkUrl = params["linkUrl"] as? String // 상품 페이지로 이동 default: break } } else { // params가 없는 이벤트 switch message.name { case "sauceflexMoveLogin": // 로그인 페이지로 이동 break default: break } } } }
💡 등록한 handler 이름(예:
"sauceflexMoveProduct")이 이벤트 key와 동일합니다. message.name으로 어떤 이벤트인지 구분합니다.
지원 이벤트 목록
소스라이브 플레이어가 전송하는 이벤트 목록과 각 이벤트의 상세 가이드입니다. 전체 params 필드 구조는 브릿지 이벤트 레퍼런스에서 확인하세요.
🧭 어떤 이벤트부터 구현해야 하나?
대부분의 쇼핑몰은 로그인 연동과 상품 클릭 연동이 필수입니다. 쿠폰·리워드는 해당 기능을 어드민에서 활성화한 경우에만 구현하면 됩니다.
대부분의 쇼핑몰은 로그인 연동과 상품 클릭 연동이 필수입니다. 쿠폰·리워드는 해당 기능을 어드민에서 활성화한 경우에만 구현하면 됩니다.
| 이벤트 key | 카테고리 | 구현 조건 | 설명 | 상세 가이드 |
|---|---|---|---|---|
| sauceflexMoveLogin | 로그인 연동 | 필수 | 게스트가 채팅·쿠폰 등 로그인 필요 기능에 접근할 때 전송됩니다. | 가이드 보기 → |
| sauceflexMoveProduct | 상품 클릭 | 필수 | 플레이어 내 상품을 클릭했을 때 전송됩니다. params.linkUrl에 상품 페이지 URL이 포함됩니다. |
가이드 보기 → |
| sauceflexMoveCoupon | 쿠폰 버튼 클릭 | 쿠폰 사용 시 | 쿠폰 버튼 클릭 시 전송됩니다. couponType으로 처리 방식을 구분합니다. 쿠폰 코드·ID 등이 포함됩니다. |
가이드 보기 → |
| sauceflexMoveReward | 리워드 CLICK 버튼 클릭 | 리워드 캠페인 시 | 리워드 달성 후 CLICK 버튼을 클릭할 때 전송됩니다. 리워드 처리를 위한 링크 URL이 포함됩니다. | 가이드 보기 → |
| sauceflexTurnOnNotification | 라이브 알림 버튼 | 라이브 알림 사용 시 | 라이브 예고 플레이어의 알림 버튼을 누를 때 전송됩니다. 알림 받기/해제 처리 후 콜백 이벤트를 다시 전송해야 합니다. | 가이드 보기 → |
📋 각 이벤트의 전체
params 필드 구조와 타입은 브릿지 이벤트 레퍼런스에서 확인하세요.
Updated about 24 hours ago