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':
      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 필드 구조와 타입은 브릿지 이벤트 레퍼런스에서 확인하세요.


bot에 문의하기