GuidesAPI GuideChangelog
Log In
Guides

브릿지 이벤트 연동

소스라이브 플레이어와 자사몰·네이티브 앱 사이의 양방향 이벤트 통신 구조입니다. 상품 클릭, 쿠폰 다운로드, 로그인 요청 등 플레이어 내 이벤트가 발생하면 자사몰에서 직접 처리할 수 있습니다. 브릿지 이벤트는 실행 환경(웹·Android·iOS)을 자동 감지하여 적합한 방식으로 이벤트를 전달합니다.

브릿지 이벤트 연동 — 소스라이브 플레이어
예상 소요 시간: 5분
📋 사전 조건: 라이브러리 기본 설정 또는 URL 연동 완료
브릿지 이벤트 동작 원리

플레이어에서 이벤트가 발생하면 실행 환경을 자동으로 감지하여 아래 세 가지 방식 중 하나로 전달합니다. 자사몰 또는 네이티브 앱은 해당 환경에 맞는 방식으로 수신 처리를 구현합니다.

소스라이브 플레이어
이벤트 발생
상품 클릭, 쿠폰 다운로드, 로그인 버튼 클릭, 리워드 달성 등의 액션 발생 시 브릿지 이벤트를 통해 전달합니다.
환경 자동 감지
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':
      // params.broadcastId · shopId · shopName 로 요청 출처 식별 가능
      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 sauceflexMoveExit() {
        // 이전 화면으로 이동
    }

    // 로그인 요청 — params(broadcastId·shopId·shopName)와 함께 호출됨
    @JavascriptInterface
    fun sauceflexMoveLogin(payload: String?) {
        val params = JSONObject(payload ?: "{}")
        val shopId = params.optString("shopId", "")
        // 로그인 페이지로 이동
    }

    // 필요한 이벤트를 추가하세요
}
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")
contentController.add(self, name: "sauceflexMoveExit")
// 필요한 이벤트를 추가하세요

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
                // 상품 페이지로 이동
            case "sauceflexMoveLogin":
                let shopId = params["shopId"] as? String
                // 로그인 페이지로 이동
            default: break
            }
        } else {
            // params가 없는 이벤트
            switch message.name {
            case "sauceflexMoveExit":
                // 이전 화면으로 이동
                break
            default: break
            }
        }
    }
}
💡 등록한 handler 이름(예: "sauceflexMoveProduct")이 이벤트 key와 동일합니다. message.name으로 어떤 이벤트인지 구분합니다.
브릿지 없이 동작하는 것

아래 동작에는 자사몰 코드가 필요하지 않습니다. 플레이어가 자체적으로 처리합니다.

  • 채팅 — 입력·전송·표시와 금칙어·차단 처리까지 플레이어 안에서 끝납니다
  • 상품·쿠폰·리워드 화면 — 목록과 버튼을 그리는 것은 플레이어가 합니다. 브릿지가 필요한 지점은 클릭한 뒤의 동작입니다
  • 쿠폰 apiDownload — 어드민에 등록한 고객사 API 를 플레이어가 직접 호출합니다
  • 쿠폰 link·newWindow — 브릿지를 등록하지 않으면 플레이어가 해당 URL 로 직접 이동시킵니다
⚠️ 브릿지가 없으면 동작하지 않는 것도 있습니다. 쿠폰 download·custom, 로그인 이동, 상품 이동, 리워드 처리, 라이브 알림 신청·해제는 자사몰이 받아서 처리해야 합니다.
지원 이벤트 목록

소스라이브 플레이어가 전송하는 이벤트 목록과 각 이벤트의 상세 가이드입니다. 전체 params 필드 구조는 브릿지 이벤트 레퍼런스에서 확인하세요.

🧭 구현 우선순위
대부분의 쇼핑몰은 로그인 연동상품 클릭 연동이 필수입니다. 쿠폰·리워드는 해당 기능을 어드민에서 활성화한 경우에만 구현합니다.
이벤트 key 카테고리 구현 조건 설명 상세 가이드
sauceflexMoveLogin 로그인 연동 필수 게스트가 채팅·쿠폰 등 로그인 필요 기능에 접근할 때 전송됩니다. params.broadcastId·shopId·shopName으로 요청 출처를 식별할 수 있습니다. 가이드 보기 →
sauceflexMoveProduct 상품 클릭 필수 플레이어 내 상품을 클릭했을 때 전송됩니다. params.linkUrl에 상품 페이지 URL이 포함됩니다. 가이드 보기 →
sauceflexMoveCoupon 쿠폰 버튼 클릭 쿠폰 사용 시 쿠폰 버튼 클릭 시 전송됩니다. couponType으로 처리 방식을 구분합니다. 쿠폰 코드·ID 등이 포함됩니다. 가이드 보기 →
sauceflexMoveReward 리워드 CLICK 버튼 클릭 리워드 캠페인 시 리워드 달성 후 CLICK 버튼을 클릭할 때 전송됩니다. 리워드 처리를 위한 링크 URL이 포함됩니다. 가이드 보기 →
sauceflexTurnOnNotification 라이브 알림 버튼 라이브 알림 사용 시 라이브 예고 플레이어의 알림 버튼을 누를 때 전송됩니다. 알림 받기/해제 처리 후 콜백 이벤트를 다시 전송해야 합니다. 가이드 보기 →
📋 각 이벤트의 전체 params 필드 구조와 타입은 브릿지 이벤트 레퍼런스에서 확인하세요.

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

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

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