고객사 Android(AOS) 애플리케이션의 네이티브 WebView를 활용하여 SauceClip 플레이어를 연동하는 방법을 안내합니다.

1. 연동 방식

연동 방식은 서비스 환경에 따라 SauceClip 도메인 URL 직접 연동(방식 A), 커스텀 도메인 연동(라이브러리 사용 - 방식 B / 라이브러리 미사용 - 방식 C) 세 가지로 구분되며, 프로젝트에 적합한 방식을 선택하여 구현할 수 있습니다.

방식 A. SauceClip 도메인 URL 직접 연동

SauceClip에서 제공하는 기본 클립 플레이어 URL을 WebView에 직접 로드합니다. 별도의 웹 개발 없이 가장 빠르고 간편하게 연동할 수 있습니다.

방식 B. 커스텀 도메인 연동 (라이브러리 사용)

고객사 도메인의 웹페이지에 SauceClip JS 라이브러리를 설치한 후, 해당 웹페이지를 WebView에 로드합니다.

플레이어 레이아웃 제어 등 웹 환경 확장이 필요할 때 적합합니다.

👉 라이브러리 및 iframe 연동이 필요한 경우, 별도 라이브러리 가이드를 참고해 주세요. 🔗라이브러리 및 iframe 연동 가이드 문서

방식 C. 커스텀 도메인 연동 (라이브러리 미사용)

고객사가 자체 웹페이지에 라이브러리를 사용하지 않고 직접 플레이어를 임베드하여 구축한 후, 해당 페이지를 WebView에 로드합니다.

2. 공통 - 사전 준비 (Prerequisites)

인터넷 접속과 원활한 숏폼 영상 재생을 위해 AndroidManifest.xml에 권한과 하드웨어 가속 설정을 추가합니다.

<uses-permission android:name="android.permission.INTERNET" />

<application
    android:hardwareAccelerated="true"
    ...>

3. 공통 - WebView 설정 (Settings)

숏폼 비디오 스트리밍과 브릿지가 정상적으로 동작하기 위해서는 아래의 필수 웹 설정이 먼저 진행되어야 합니다.

import android.annotation.SuppressLint
import android.graphics.Bitmap
import android.webkit.WebChromeClient
import android.webkit.WebView
import android.webkit.WebViewClient

@SuppressLint("SetJavaScriptEnabled")
fun setupWebView(webView: WebView) {
    val settings = webView.settings
    
    // 필수 설정
    settings.javaScriptEnabled = true // JS 브릿지 및 플레이어 동작에 필수
    settings.domStorageEnabled = true // 로컬 스토리지 사용 허용
    settings.mediaPlaybackRequiresUserGesture = false // 사용자 터치 없이 영상 자동 재생 허용
    settings.useWideViewPort = true
    settings.loadWithOverviewMode = true

    webView.webViewClient = object : WebViewClient() {}

    webView.webChromeClient = object : WebChromeClient() {
        // [중요] 영상 로딩 시 기본 재생 아이콘(검은 화면) 숨김 처리
        override fun getDefaultVideoPoster(): Bitmap? {
            return Bitmap.createBitmap(10, 10, Bitmap.Config.ARGB_8888)
        }
    }
}

4. 로드 구현

선택한 방식에 맞게 URL을 로드합니다.

방식 A. SauceClip URL 직접 로드

val clipId = "YOUR_CLIP_ID" 
val sauceClipUrl = "[https://player.sauceflex.com/clip/$clipId](https://player.sauceflex.com/clip/$clipId)" // 예시 URL이며 발급받은 실제 URL을 사용하세요.
webView.loadUrl(sauceClipUrl)

방식 B / C. 고객사 커스텀 웹페이지 로드

라이브러리 사용 여부(방식 B, C)와 관계없이, Android 앱에서는 동일하게 고객사 도메인으로 구축된 웹페이지 URL을 로드합니다.

val clientDomainUrl = "[https://www.your-domain.com/clip-player?clipId=YOUR_CLIP_ID](https://www.your-domain.com/clip-player?clipId=YOUR_CLIP_ID)"
webView.loadUrl(clientDomainUrl)

5. JavaScript 브릿지 연동 (Bridge Integration)

플레이어 내부에서 발생하는 액션(상품 클릭, 공유하기 등)을 네이티브 앱에서 처리하려면 JavascriptInterface를 등록해야 합니다.

5.1 브릿지 객체 생성

import android.content.Context
import android.webkit.JavascriptInterface

class SauceClipBridge(private val context: Context) {

    // 예시 1: 상품 클릭 시
    @JavascriptInterface
    fun sauceclipMoveProduct(payload: String) {
        // 전달받은 JSON(payload)을 파싱하여 네이티브 상품 상세 화면으로 이동 처리
    }

    // 예시 2: 공유하기 버튼 클릭 시
    @JavascriptInterface
    fun sauceclipOnShare(payload: String) {
        // 전달받은 JSON(payload)을 파싱하여 Android Native 공유 Intent 실행
    }
    
    // 그 외 Payload 문서에 정의된 메서드들을 필요에 따라 추가 구현합니다.
}

// 웹(플레이어)에서 'AndroidBridge'라는 인터페이스 명칭으로 호출할 수 있도록 연결합니다.
// webView.addJavascriptInterface(SauceClipBridge(context), "AndroidBridge")

👉 전체 Payload 규격 및 메서드는 🔗 SauceClip Payload 스펙 가이드 문서 참고해 주세요.

5.2 WebView에 브릿지 연결

// Bridge 클래스 초기화 시 context와 webView 인스턴스를 함께 넘겨줍니다.
webView.addJavascriptInterface(SauceClipBridge(this, webView), "AndroidBridge")