GuidesAPI GuideChangelog
Log In
Guides

앱 웹뷰 브릿지

앱이 웹뷰로 소스라이브 플레이어를 열 때 앱에서 구현할 브릿지입니다. 웹뷰로 여는 주소가 소스라이브 플레이어 웹 SDK를 설치한 자사몰 페이지인지, 플레이어 주소인지에 따라 이벤트를 받는 곳과 앱이 할 일이 달라집니다.

앱 웹뷰 브릿지 — 소스라이브 플레이어
📱 대상: Android · iOS 앱 개발자
📋 사전 조건: 웹뷰 JavaScript 활성화
웹뷰로 여는 주소에 따른 차이

앱 화면 구성에 맞는 방식을 선택하세요.

웹뷰로 여는 주소이럴 때이벤트를 받는 곳앱이 등록할 것
웹 SDK를 설치한 자사몰 페이지자사몰 웹 화면을 앱에서 그대로 보여 줄 때자사몰 페이지의 on() 처리 함수앱이 정한 이름의 브릿지 하나. sauceflex… 이름은 등록하지 않음
플레이어 주소(웹 SDK 없이 iframe으로 넣은 플레이어도 같음)플레이어만 열 때. PIP 해제 알림 · 앱스플라이어 이벤트가 필요할 때앱의 네이티브 브릿지받을 sauceflex… 이름
📘 방식 선택 기준
자사몰 웹 화면을 보여 준다면 자사몰 페이지를 여는 방식을 선택하세요. 플레이어만 열거나 PIP 해제 알림 · 앱스플라이어 이벤트가 필요하면 플레이어 주소를 여는 방식을 권장합니다.
❗ PIP 해제 알림과 앱스플라이어 이벤트는 웹 SDK에 없습니다. PIP 버튼 클릭은 pipClick으로 받습니다.
📘 웹뷰 설정과 PIP 창 구현은 Android 웹뷰 연동 · iOS 웹뷰 연동을 확인하세요.
자사몰 페이지를 열 때

앱에 브릿지 하나(예: shopApp)를 등록하고, 자사몰 페이지의 처리 함수가 이벤트를 그 브릿지로 넘기게 하세요.
처리 함수는 앱 웹뷰 안에서만 등록하세요. 웹 브라우저에서도 등록하면 상품이나 닫기를 눌러도 기본 이동이 실행되지 않습니다.

JavaScript — 자사몰 페이지
// 자사몰 페이지 코드. shopApp은 예시 이름이다. 앱에서 등록한 이름으로 바꾼다
const androidApp = window.shopApp
const iosApp = window.webkit?.messageHandlers?.shopApp
const sendToApp = (name, value) => {
  const message = JSON.stringify({ name, value })
  if (androidApp) androidApp.postMessage(message)  // Android
  else if (iosApp) iosApp.postMessage(message)  // iOS
}

// 앱 웹뷰 안에서 열렸을 때만 등록한다. 웹 브라우저에서는 웹 SDK 기본 동작을 쓴다
if (androidApp || iosApp) {
  SauceLive.Player('on', 'productClick', (e) => sendToApp('productClick', e))
  SauceLive.Player('on', 'closeClick', (e) => sendToApp('closeClick', e))
}
Kotlin
// 자사몰 페이지의 window.shopApp.postMessage(message)가 이 메서드를 호출한다
class ShopAppBridge(private val activity: Activity) {
    @JavascriptInterface
    fun postMessage(message: String) {
        val json = JSONObject(message)    // { name, value }
        val value = json.optJSONObject("value")
        when (json.optString("name")) {
            "productClick" -> {
                val linkUrl = value?.optString("linkUrl")
                activity.runOnUiThread { /* 상품 화면으로 이동 */ }
            }
            "closeClick" -> activity.runOnUiThread { activity.finish() }
        }
    }
}

// 등록 이름은 자사몰 페이지 코드의 shopApp과 같게

webView.settings.javaScriptEnabled = true
webView.addJavascriptInterface(ShopAppBridge(this), "shopApp")

// 앱에서 플레이어를 제어할 때는 웹 SDK 명령을 실행한다

webView.evaluateJavascript("SauceLive.Player('pause')", null)
Swift
// 등록 이름은 자사몰 페이지 코드의 shopApp과 같게
let contentController = WKUserContentController()

contentController.add(self, name: "shopApp")
let config = WKWebViewConfiguration()

config.userContentController = contentController
let webView = WKWebView(frame: .zero, configuration: config)

extension ViewController: WKScriptMessageHandler {
    func userContentController(_ userContentController: WKUserContentController,
                               didReceive message: WKScriptMessage) {
        // body는 자사몰 페이지가 보낸 JSON 문자열 { name, value }
        guard message.name == "shopApp",
              let data = (message.body as? String)?.data(using: .utf8),
              let json = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any]
        else { return }
        let value = json["value"] as? [String: Any] ?? [:]

        switch json["name"] as? String {
        case "productClick":
            let linkUrl = value["linkUrl"] as? String
            // 상품 화면으로 이동
        case "closeClick":
            navigationController?.popViewController(animated: true)
        default: break
        }
    }
}

// 앱에서 플레이어를 제어할 때는 웹 SDK 명령을 실행한다

webView.evaluateJavaScript("SauceLive.Player('pause')")
⚠️ 이 방식에서는 sauceflex… 이름을 하나도 등록하지 마세요. 앱이 등록한 이름의 이벤트는 라이프사이클 이벤트까지 앱으로만 전달되어 on()이 받지 못합니다.
플레이어 주소를 열 때: 브릿지 등록

받을 이름만 sauceflex… 이름으로 등록하세요. 등록한 이름은 플레이어 대신 앱이 처리합니다.
이름 · 값 · 앱이 할 일은 브릿지 이벤트 레퍼런스의 sauceflex… 이름 표에 있습니다.

Kotlin
class SauceflexBridge(private val activity: Activity) {
    // 값이 있는 이름: JSON 문자열 하나를 받는다
    @JavascriptInterface
    fun sauceflexMoveProduct(payload: String) {
        val linkUrl = JSONObject(payload).optString("linkUrl")
        activity.runOnUiThread { /* 상품 화면으로 이동 */ }
    }

    // 값이 없는 이름: 인자 없이 호출된다
    @JavascriptInterface
    fun sauceflexMoveExit() {
        activity.runOnUiThread { activity.finish() }
    }

    // 로그인 요청도 Android에서는 기본으로 인자 없이 호출된다
    @JavascriptInterface
    fun sauceflexMoveLogin() {
        activity.runOnUiThread { /* 로그인 화면으로 이동 */ }
    }
}

// 등록 이름은 "sauceflex"로 고정

webView.settings.javaScriptEnabled = true
webView.addJavascriptInterface(SauceflexBridge(this), "sauceflex")
Swift
// 받을 이름마다 핸들러를 등록
let contentController = WKUserContentController()

["sauceflexMoveProduct", "sauceflexMoveLogin", "sauceflexMoveExit"]
    .forEach { contentController.add(self, name: $0) }
let config = WKWebViewConfiguration()

config.userContentController = contentController
let webView = WKWebView(frame: .zero, configuration: config)

extension ViewController: WKScriptMessageHandler {
    func userContentController(_ userContentController: WKUserContentController,
                               didReceive message: WKScriptMessage) {
        // message.name으로 구분한다. 값이 있으면 body가 JSON 문자열, 없으면 NSNull
        let params = (message.body as? String)
            .flatMap { $0.data(using: .utf8) }
            .flatMap { try? JSONSerialization.jsonObject(with: $0) as? [String: Any] } ?? [:]

        switch message.name {
        case "sauceflexMoveProduct":
            let linkUrl = params["linkUrl"] as? String
            // 상품 화면으로 이동
        case "sauceflexMoveLogin":
            let shopId = params["shopId"] as? String
            // 로그인 화면으로 이동
        case "sauceflexMoveExit":
            navigationController?.popViewController(animated: true)
        default: break
        }
    }
}
⚠️ Android 메서드는 인자 수를 맞게 선언하세요. 표에서 값이 「없음」인 이름은 인자 없이 선언합니다. 인자 수가 다르면 호출되지 않습니다.
플레이어 주소를 열 때: 플레이어로 보내기

앱은 웹뷰에서 window.postMessage(JSON.stringify({ key, params }), '*')를 실행해 플레이어로 보냅니다.
라이브 알림 요청을 받았다면 결과를 반드시 보내세요. 보내지 않으면 알림 버튼이 잠긴 채 남습니다. 시청자가 앱에서 로그인하면 accessToken 쿼리를 붙인 플레이어 주소를 웹뷰에 다시 불러오세요(URL 연동).

Kotlin
// 플레이어에 정지 요청
webView.evaluateJavascript(
    "window.postMessage(JSON.stringify({ key: 'sauceflexPause' }), '*')", null
)

// 알림 신청 결과 돌려주기

webView.evaluateJavascript(
    "window.postMessage(JSON.stringify({ key: 'sauceflexTurnOnNotificationCallback', " +
    "params: { broadcastId: '$broadcastId', result: 'success' } }), '*')", null
)
Swift
// 앱이 PIP 로 바뀌었음을 플레이어에 알림
webView.evaluateJavaScript(
    "window.postMessage(JSON.stringify({ key: 'sauceFlexPIP', params: true }), '*')"
)

// 알림 신청 결과 돌려주기

webView.evaluateJavaScript(
    "window.postMessage(JSON.stringify({ key: 'sauceflexTurnOnNotificationCallback', " +
    "params: { broadcastId: '\(broadcastId)', result: 'success' } }), '*')"
)

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

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

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