Guides

소스클립 플레이어 v1.1.0

1. 소개

소스클립 영상 주소로 접근했을 때 보여지는 페이지입니다. 일반적으로 브라우저에서 그대로 사용하시면 됩니다.

소스클립 플레이어에서 제공하는 이벤트에 대한 가이드 입니다.


2-1. 연동 방법 (기본 - 소스클립 플레이어 랜딩)

기본적으로는 소스클립의 기능을 그대로 사용합니다.

그 외 파트너사 자사몰에 연동하는 경우는 아래 JSON필드 내용 예시를 참고해 적용합니다.

  • 소스클립 입장
    • 기본 동작은 없습니다.
  • 공유하기
    • SNS (ex. kakao, facebook) 공유하기는 지원하지 않으며, 주소 복사하기 기능만 가능합니다.
  • 소스클립 닫기 URL
    • 기본 동작은 history.back() 입니다.

{
    /* 닫기버튼 관련(❌ 뒤로가기시와 다르게 동작합니다.) */
    "close": {
        /* 히스토리 방법 */                
        /* Type "href" | "replace" defaultValue "href" href= "히스토리 추가되어 동작",replace="현재 페이지 히스토리를 변경" */
        "history": "href",
        /* 모바일주소 */
        /* Type string | null defaultValue null*/
        /* 예시) "https://space.sauceflex.com"*/
        "mobile": null,
        /* PC주소 */
        /* Type string | null */
        /* 예시) "https://space.sauceflex.com"*/
        "pc": null,
        /* 웹뷰스킴 호출 */
        /* Type string | null */
        /* 적용 예시) "webivew":"sauceclipapp://close" */
        "webview": null
    },
    /* 방송 테마 설정 */
    /* Type RGB color */
    /* 예시) "222,46,95*/
    "theme": {
        "bgColor": null
    },
    /* 상점 정보 노출 설정 */
    /* Type true || false // default true */
    /* 예시) true */
    "store": {
        "isStore": true
    }
}
//  적용안(참고용)
{
    "close": {
        "history": "href",
        "mobile": "https://space.sauceflex.com",
        "pc": "https://space.sauceflex.com",
        "webview": null
    },
    "theme": {
        "bgColor": "222,46,95"
    },
    "store": {
        "isStore": true
    }
}

📘

https://player.sauceclip.com/player?clipId={소스클립ID}&partnerId={파트너ID}

  • WebView에서 플레이어 연동 시 참고 사항
    • iOS X 이상의 기기에서 플레이어 화면 잘림 현상을 방지하기 위해 SafeArea 영역 설정을 필히 진행해 주시기 바랍니다.
    • Android Webview에서 재생 아이콘 표시 없이 영상이 재생되는 것을 원하실 경우에는 아래 코드를 활용해주세요. (해당 가이드는 파트너사 AOS앱 개발팀에서 진행)
      • override fun getDefaultVideoPoster(): Bitmap? { return Bitmap.createBitmap(10,10, Bitmap.Config.ARGB_8888) }

2-2. 연동 방법 (Iframe)

STEP1. 기능 사용 여부 ⭐️ stage, prod 환경 설정 - 궁금한 내용은 카카오톡, 채널톡 또는 담당자 이메일 [email protected] 문의

{
    /* 닫기버튼 설정 */
    "close": {
        "history": "href",
        "mobile": "https://space.sauceflex.com",
        "pc": "https://space.sauceflex.com",
        "webview": null
    },
    /* 방송 테마 설정 */
    "theme": {
        "bgColor": "222,46,95"
    },
    /* 상점 정보 노출 설정 */
    "store": {
        "isStore": true
    }
}

STEP 2. 방송 페이지를 iframe 을 이용하여 페이지에 추가 합니다.

<!-- 방송 주소 -->
<iframe src="https://player.sauceclip.com/player?clipId={소스클립ID}&amp;partnerId={파트너ID}&gt;"&gt;</iframe>
<!-- 외부 유입 코드를 사용하려면 iframe을 그리기 전 요청받은 파라미터를 전달해줘야 합니다. 부모페이지에 호출된 queryString key중 fc 의 값을 전달해주셔야 합니다. -->
<!-- example -->
<iframe src="https://player.sauceclip.com/player?clipId={소스클립ID}&amp;partnerId={파트너ID}&amp;fc=value"></iframe>

STEP 3. 자바스크립트 window 객체에 'message' 이벤트를 수신하고 각 이벤트에 대해서 적절히 처리합니다.

window.addEventListener(
    "message",
    function(e) {
        // 이곳에 처리
        console.log(e.data);
    }, false
);

STEP 4. 메시지는 이벤트의 'data' 를 통해 JSON Type으로 전달됩니다.

📘

전달되는 데이터의 브릿지명과 페이로드는 '3. 브릿지' 항목을 참고해주세요.


2-3. 연동방법 (Webview)

Android

안드로이드의 경우 "sauceclip" 이름을 가진 브릿지 중 해당 브릿지가 있는 경우 메시지를 전달하게 되며, 기본 동작은 취소됩니다.

import android.os.Handler
import android.webkit.JavascriptInterface
import android.widget.Toast
 
class AndroidBridge(private val activity: MainActivity) {
    private val handler = Handler()
 
    @JavascriptInterface
    fun sauceclipEnter() {
        handler.post {
            Toast.makeText(activity, "sauceclipEnter", Toast.LENGTH_SHORT).show()
        }
    }
 
    @JavascriptInterface
    fun sauceclipMoveExit() {
        handler.post {
            Toast.makeText(activity, "sauceclipMoveExit", Toast.LENGTH_SHORT).show()
        }
    }
 
    @JavascriptInterface
    fun sauceclipMoveProduct(message: String) {
        handler.post {
            Toast.makeText(activity, "sauceclipMoveProduct \\n $message", Toast.LENGTH_SHORT).show()
        }
    }

    @JavascriptInterface
    fun sauceclipAddCart(message: String) {
        handler.post {
            Toast.makeText(activity, "sauceclipAddCart \\n $message", Toast.LENGTH_SHORT).show()
        }
    }

    @JavascriptInterface
    fun sauceclipMoveCart() {
        handler.post {
            Toast.makeText(activity, "sauceclipMoveCart", Toast.LENGTH_SHORT).show()
        }
    }
 
    @JavascriptInterface
    fun sauceclipOnShare(message: String) {
        handler.post {
            Toast.makeText(activity, "sauceclipOnShare \\n $message", Toast.LENGTH_SHORT).show()
        }
    }

    @JavascriptInterface
    fun sauceclipPlayerError(message: String) {
        handler.post {
            Toast.makeText(activity, "sauceclipPlayerError \\n $message", Toast.LENGTH_SHORT).show()
        }
    }
 
}

iOS

extension ViewController: WKScriptMessageHandler {
    func userContentController(_ userContentController: WKUserContentController,
                                    didReceive message: WKScriptMessage) {
        switch (message.name) {
            case "sauceclipEnter":
                print("sauceclipEnter")
                break
 
            case "sauceclipMoveExit":
                print("sauceclipMoveExit")
                break
 
            case "sauceclipMoveProduct":
                print("sauceclipMoveProduct")
                print(message.body)
                break
            
            case "sauceclipAddCart":
                print("sauceclipAddCart")
                print(message.body)
                break

            case "sauceclipMoveCart":
                print("sauceclipMoveCart")
                break

            case "sauceclipOnShare":
                print("sauceclipOnShare")
                print(message.body)
                break

            case "sauceclipPlayerError":
                print("sauceclipPlayerError")
                print(message.body)
                break
 
            default:
                print("message.name \\(message.name) not handled.")
        }
    }
}

3. 브릿지

📘

브릿지의 페이로드는 JSON형식의 객체가 문자열로 변환되어 제공됩니다.

브릿지 목록

  • 클립 진입 브릿지
  • 클립 나가기 클릭 브릿지
  • 상품 페이지 이동 클릭 브릿지
  • 장바구니 담기 클릭 브릿지
  • 장바구니 페이지 이동 클릭 브릿지
  • 공유하기 클릭 브릿지
  • 에러 정보 브릿지

클립 진입 브릿지

브릿지명

: sauceclipEnter

페이로드

  • 없음

클립 나가기 클릭 브릿지

브릿지명

: sauceclipMoveExit

페이로드

  • 없음

상품 페이지 이동 클릭 브릿지

브릿지명

: sauceclipMoveProduct

페이로드

{
  clipIdx: {{클립 ID}},
  externalProductId: {{상품 코드}},
  linkUrl: {{상품 링크}},
  productId: {{상품 ID}},
}
  • clipIdx
    • 타입: String
    • 설명: 클립 ID
  • externalProductId
    • 타입: String
    • 설명: 상품 코드
  • linkUrl
    • 타입: String
    • 설명: 상품 링크
  • productId
    • 타입: Integer
    • 설명: 상품 ID

장바구니 담기 클릭 브릿지

브릿지명

: sauceclipAddCart

페이로드

{
  clipIdx: {{클립 ID}},
  optionCode: {{상품 옵션 코드}},
  price: {{상품 가격}}, 
  productCode: {{상품 코드}},
  productId: {{상품 ID}},
  productImg: {{상품 이미지 링크}},
  productName: {{상품명}},
}
  • clipIdx
    • 타입: String
    • 설명: 클립 ID
  • optionCode
    • 타입: String | Null
    • 설명: 상품 옵션 코드
    • 특징: 상품 옵션 목록에서 카트 담기 클릭 시에만 전달되는 항목
  • price
    • 타입: String
    • 설명: 상품 가격
  • productCode
    • 타입: String
    • 설명: 상품 코드
  • productId
    • 타입: Integer
    • 설명: 상품 ID
  • productImg
    • 타입: String
    • 설명: 상품 이미지 링크
  • productName
    • 타입: String
    • 설명: 상품명

장바구니 페이지 이동 클릭 브릿지

브릿지명

: sauceclipMoveCart

페이로드

{}
  • 빈 객체

공유하기 클릭 브릿지

브릿지명

: sauceclipOnShare

페이로드]

{
  clipId: {{클립 ID}},
  curationId: {{큐레이션 ID}},
  linkUrl: {{공유 링크}},
  partnerId: {{파트너 ID}},
  tags: {{클립 태그 목록}},
  thumbnailUrl: {{클립 이미지 링크}},
  title: {{클립 타이틀}},
}
  • clipId
    • 타입: String
    • 설명: 클립 ID
  • curationId
    • 타입: String
    • 설명: 큐레이션 ID
  • linkUrl
    • 타입: String
    • 설명: 공유 링크
  • partnerId
    • 타입: String
    • 설명: 파트너 ID
  • tags
    • 타입: String[]
    • 설명: 클립 태그 목록
  • thumbnailUrl
    • 타입: String
    • 설명: 클립 이미지 링크
  • title
    • 타입: String
    • 설명: 클립 타이틀

에러 정보 브릿지

브릿지명

: sauceclipPlayerError

페이로드

{
  errorCode: {{에러코드}},
  errorDetails: {{에러 상세 내용}},
  errorType: {{에러 타입}},
}
  • errorCode
    • 타입: String
    • 설명
      • API에러인 경우, 상태 코드
      • Hls에러인 경우, 에러 타입
      • UI에러인 경우, 에러 메시지
  • errorDetails
    • 타입: String
    • 설명: 에러 상세 내용
  • errorType
    • 타입: String ('api' | 'hls' | 'ui')
    • 설명
      • api: API 관련 에러
      • hls: Hls 관련 에러
      • ui: UI 관련 에러

🚦본 문서는 부정 경쟁 방지 및 영업 비밀 보호에 관한 법령에 따라 보호의 대상이 되는 영업 비밀, 산업 기술을 포함합니다.

🚦본 문서에 포함된 정보의 전부 또는 일부를 무단으로 제 3자에게 공개, 배포, 복사 또는 사용하는 것은 엄격히 금지됩니다.