Guides

소스클립 플레이어

Suggest Edits

1. 소개

짧은 영상에 상품을 연동하는 커머스에 특화된 숏폼 서비스로, 웹브라우저나 앱의 웹뷰에서 이용할 수 있는 URL이 제공됩니다.

2. 연동 방법

연동 방법에는 링크 이동 방식과, iframe 연동 방식, Webview 연동 방식을 사용하는 방법으로 구분됩니다.

📘

앱에서 연동하는 경우에는 반드시 Webview 연동 방식으로 연동해주세요.

컨피그 설정

소스클립 컨피그 설정하기 페이지를 참고해서 모비두 담당자에게 문의하여 설정합니다.

링크 이동 방식

직접 플레이어 링크로 이동하는 경우, 이동할 URL에 다음 형식의 값을 지정합니다.

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

📘

iframe 연동 방식

STEP 1. 페이지 내 적용하려는 위치에 플레이어 링크를 연결한 iframe태그를 다음과 같이 추가합니다.

  • 외부 유입 코드를 사용하지 않는 경우
<iframe src="https://player.sauceclip.com/player?clipId={{소스클립ID}}&partnerUniqueId={{파트너ID}}"</iframe>
  • 외부 유입 코드를 사용하는 경우, 적용하려는 페이지 URL의 쿼리스트링에 존재하는 fc의 값을 추가해주세요.
<iframe src="https://player.sauceclip.com/player?clipId={{소스클립ID}}&partnerUniqueId={{파트너ID}}&fc={{fc값}}"></iframe>

STEP 2. window 객체에 message이벤트 핸들러를 구현하여 브릿지를 연동합니다.

window.addEventListener(
    "message",
    function(event) {
        console.log(event.data);
    }, false
);

📘

  • 브릿지의 페이로드는 JSON형식의 객체가 문자열로 변환되어 제공됩니다.
  • 전달되는 데이터의 브릿지명과 페이로드는 '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()
        }
    }
 
}

📘

Android Webview에서 재생 아이콘 표시 없이 영상이 재생되는 것을 원하실 경우에는 아래 코드를 활용해주세요. (해당 가이드는 파트너사 AOS앱 개발팀에서 진행)

  • override fun getDefaultVideoPoster(): Bitmap? { return Bitmap.createBitmap(10,10, Bitmap.Config.ARGB_8888) }

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.")
        }
    }
}

📘

iOS X 이상의 기기에서 플레이어 화면 잘림 현상을 방지하기 위해 SafeArea 영역 설정을 필히 진행해 주시기 바랍니다.

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에러인 경우, 상태 코드
      • UI에러인 경우, 에러 메시지
      • 비디오 에러인 경우, 에러 코드나 hls 에러타입
  • errorDetails
    • 타입: String
    • 설명: 에러 상세 내용
  • errorType
    • 타입: String ('api' | 'ui' | 'video')
    • 설명
      • api: API 관련 에러
      • ui: UI 관련 에러
      • video: 비디오 관련 에러

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

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

Updated 3 months ago