Shoplive 숏폼 SDK 연동 가이드

// ① Swift Package Manager
// Xcode ▸ File ▸ Add Package Dependencies…
dependencies: [
    .package(url: "https://github.com/shoplive/shortform-ios", .upToNextMajor(from: "1.8.13")),
    .package(url: "https://github.com/shoplive/common-ios",    .upToNextMajor(from: "1.8.13")),
]

// ② CocoaPods — Podfile
// pod 'ShopliveShortformSDK', '1.8.13'
// pod 'ShopliveSDKCommon',    '1.8.13'

// ③ import
import ShopliveSDKCommon        // accessKey · 사용자 인증 · 공용 모델
import ShopLiveShortformSDK     // 숏폼 재생 · 컬렉션 · 프리뷰

// settings.gradle / build.gradle — mavenCentral() 필요
dependencies {
    implementation("cloud.shoplive:shoplive-short-form:1.8.14")   // 숏폼
    implementation("cloud.shoplive:shoplive-common:1.8.14")       // 공통 (accessKey · 인증)
    implementation("cloud.shoplive:shoplive-network:1.8.14")      // 네트워크

    // 재생 엔진 — 아래 둘 중 <b>하나만</b> 선언하세요 (엔진 버전은 SDK 버전과 별개 체계)
    implementation("cloud.shoplive:shoplive-media3:1.10.1.3")     // media3 (기본) — minSdk 23
    // implementation("cloud.shoplive:shoplive-exoplayer:2.19.1.20")  // ExoPlayer (레거시) — minSdk 19
}

android {
    defaultConfig { multiDexEnabled = true }
}

// 1) 앱 시작 시 1회 (AppDelegate)
ShopLiveCommon.setAccessKey(accessKey: "발급받은_ACCESS_KEY")

// 2) 재생 — 조건 없이 부르면 전체 숏폼
ShopLiveShortform.play(requestData: ShopLiveShortformCollectionData(delegate: nil))

// 1) 앱 시작 시 1회 (Application.onCreate)
ShopLiveCommon.setAccessKey("발급받은_ACCESS_KEY")

// 2) 재생 — 조건 없이 부르면 전체 숏폼
ShopLiveShortform.play(context)

let data = ShopLiveShortformCollectionData(
    tags: ["봄신상", "아우터"],
    tagSearchOperator: .AND,        // 모든 태그를 만족 (.OR = 하나라도)
    brands: ["shoplive"],
    shuffle: true,
    skus: ["SKU-1001"],
    shortsCollectionId: "COLLECTION_ID",
    isMuted: false,
    delegate: self                  // 이벤트 수신 — 미션 5
)
ShopLiveShortform.play(requestData: data)

val data = ShopLiveShortformCollectionData().apply {
    tags = listOf("봄신상", "아우터")
    tagSearchOperator = ShopLiveShortformTagSearchOperator.AND
    brands = listOf("shoplive")
    shuffle = true
    skus = listOf("SKU-1001")
    shortsCollectionId = "COLLECTION_ID"
    isMuted = false
    handler = myHandler             // 이벤트 수신 — 미션 5
}
ShopLiveShortform.play(context, data)

@IBAction func openShorts() {
    let data = ShopLiveShortformCollectionData(
        tags: ["봄신상"],
        tagSearchOperator: .AND,
        shuffle: true,
        delegate: self          // 선택: 이벤트 수신
    )
    ShopLiveShortform.play(requestData: data)
}

fun openShorts() {
    val data = ShopLiveShortformCollectionData().apply {
        tags = listOf("봄신상")
        tagSearchOperator = ShopLiveShortformTagSearchOperator.AND
        shuffle = true
        handler = myHandler     // 선택: 이벤트 수신
    }
    ShopLiveShortform.play(context, data)
}

ShopLiveShortform.close()      // 앱이 강제로 닫을 때 (예: 로그아웃, 딥링크 전환)

ShopLiveShortform.close()      // 앱이 강제로 닫을 때 (예: 로그아웃, 딥링크 전환)

// iOS — 빌더로 만들고 getView() 로 꺼내 붙입니다.
private var builder: ShopLiveShortform.CardTypeViewBuilder?

override func viewDidLoad() {
    super.viewDidLoad()

    let builder = ShopLiveShortform.CardTypeViewBuilder()
    let listView = builder.build(
        cardViewType: .type1,
        listViewDelegate: self,
        shortsCollectionDelegate: self,   // 상품·공유 이벤트 — 미션 5
        enableSnap: false,
        enablePlayVideo: true,
        playOnlyOnWifi: false,
        cellSpacing: 8,
        cellRadius: 16,
        viewCountVisibility: true
    ).getView()

    listView.translatesAutoresizingMaskIntoConstraints = false
    view.addSubview(listView)
    // … 오토레이아웃 제약 …

    builder.setHashTags(tags: ["봄신상"], tagSearchOperator: .AND)
    builder.submit()                       // ← 조건 확정 후 반드시 호출
    self.builder = builder
}

// Android — XML 에 뷰를 놓고, 코드에서 설정한 뒤 submit()
// res/layout/fragment_home.xml
// <cloud.shoplive.sdk.shorts.ShopLiveShortformCardTypeView
//     android:id="@+id/shortsCardTypeView"
//     android:layout_width="match_parent"
//     android:layout_height="0dp" />

with(binding.shortsCardTypeView) {
    setSpanCount(2)                                        // 그리드 열 개수
    setViewType(ShopLiveShortform.CardViewType.CARD_TYPE1)
    handler = myHandler                                    // 상품·공유 이벤트 — 미션 5
    setHashTags(listOf("봄신상"), ShopLiveShortformTagSearchOperator.AND)
    submit()                                               // ← 조건 확정 후 반드시 호출
}

// 세로형 / 가로형은 ListViewBuilder 로
let builder = ShopLiveShortform.ListViewBuilder()
let listView = builder.build(
    cardViewType: .type1,
    listViewType: .horizontal,        // .vertical | .horizontal
    playableType: .CENTER,            // 가로형에서 어떤 셀을 재생할지
    listViewDelegate: self,
    shortsCollectionDelegate: self
).getView()
builder.submit()

// 세로형 — ShopLiveShortformVerticalTypeView
with(binding.shortsVerticalTypeView) {
    setSpanCount(2)
    setViewType(ShopLiveShortform.CardViewType.CARD_TYPE1)
    submit()
}

// 가로형 — ShopLiveShortformHorizontalTypeView
with(binding.shortsHorizontalTypeView) {
    setViewType(ShopLiveShortform.CardViewType.CARD_TYPE1)
    setPlayableType(ShopLiveShortform.PlayableType.CENTER)
    enableSnap()
    submit()                                     // ← 가로형도 submit() 이 필요합니다
}

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    builder?.enablePlayVideos()
}

override func viewDidDisappear(_ animated: Bool) {
    super.viewDidDisappear(animated)
    builder?.disablePlayVideos()
}

override func viewWillTransition(to size: CGSize, with c: UIViewControllerTransitionCoordinator) {
    super.viewWillTransition(to: size, with: c)
    builder?.notifyViewRotated()          // 회전 시 레이아웃 재계산
}

override fun onResume() {
    super.onResume()
    binding.shortsCardTypeView.enablePlayVideos()
}

override fun onPause() {
    super.onPause()
    binding.shortsCardTypeView.disablePlayVideos()
}

let feed = ShopLiveShortsCollectionView(
    requestData: ShopLiveShortformCollectionData(tags: ["봄신상"], delegate: self)
)
view.addSubview(feed)

feed.resultHandler = { result in
    if case .didScrollToShortsId(let shortsId) = result {
        print("현재 숏폼: \(shortsId ?? "")")
    }
}

feed.action(.play)          // .pause · .setMuted(true) · .setScrollEnabled(false) 등

// res/layout — <cloud.shoplive.sdk.shorts.ShopLiveShortformDetailTypeView … />
with(binding.shortsDetailTypeView) {
    setMuted(false)
    setUIComponentPadding(bottom = bottomNavHeight)   // 하단 탭바에 가리지 않게
    setHashTags(listOf("봄신상"), ShopLiveShortformTagSearchOperator.AND)
    submit()                                          // ← 조건 확정 후 반드시 호출
}

// 시스템 뒤로가기를 피드에 전달
override fun onBackPressed() {
    binding.shortsDetailTypeView.onBackPressed()
}

let preview = ShopLiveShortformPreviewData(
    productId: "PRODUCT_ID",
    isMuted: true,
    previewPosition: .bottomRight,
    previewRadius: 12,
    previewEdgeInset: .init(top: 0, left: 0, bottom: 24, right: 16),
    useCloseButton: true,
    enableSwipeOut: true,
    maxCount: 10,
    delegate: self
)
ShopLiveShortform.showPreview(requestData: preview)

// 내릴 때
ShopLiveShortform.close()

ShopLiveShortform.hidePreview()          // 중복 방지: 띄우기 전 한 번 내림
ShopLiveShortform.showPreview(
    activity,
    ShopLiveShortformPreviewData().apply {
        productId = "PRODUCT_ID"
        isMuted = true
        setPosition(ShopLivePreviewPositionConfig.BOTTOM_RIGHT)
        setRadius(12f)
        setMarginBottom(24)
        setMarginRight(16)
        setUseCloseButton(true)
        setIsAutoClosed(true)
        maxCount = 10
        handler = myHandler
    }
)

// 내릴 때
ShopLiveShortform.hidePreview()
// 현재 떠 있는지 확인
if (ShopLiveShortform.isShowingPreview()) { /* … */ }

// ① 로그인 · 보안 인증 (권장) — 백엔드가 서명한 JWT (4단계)
ShopLiveCommon.setAuthToken(authToken: myJwtFromServer)

// ② 로그인 · 간편 — 프로필 직접 전달 (서명 없음 · 권한 검증에 쓰지 않음)
ShopLiveCommon.setUser(user: ShopLiveCommonUser(
    userId: hashedUserId,          // 원문 회원 ID 대신 해시값 (3단계)
    userName: "홍길동",
    age: 29,
    gender: .male,
    userScore: 3
))

// ③ 비로그인 — 호출하지 않아도 됩니다

// 로그아웃 — 사용자 정보 초기화 (JWT·프로필을 지운다)
ShopLiveCommon.setAuthToken(authToken: nil)
ShopLiveCommon.setUser(user: nil)

// 현재 로그인 상태
let isLoggedIn = ShopLiveCommon.isLoggedIn()

// ① 로그인 · 보안 인증 (권장) — 백엔드가 서명한 JWT (4단계)
ShopLiveCommon.setAuthToken(myJwtFromServer)

// ② 로그인 · 간편 — 프로필 직접 전달 (서명 없음 · 권한 검증에 쓰지 않음)
ShopLiveCommon.setUser(
    ShopLiveCommonUser(userId = hashedUserId).apply {   // 원문 회원 ID 대신 해시값 (3단계)
        setUserName("홍길동")
        setAge(29)
        setGender(ShopLiveCommonUserGender.MALE)
    }
)

// ③ 비로그인 — 호출하지 않아도 됩니다

// 로그아웃 — 사용자 정보 초기화 (JWT·프로필을 지운다)
ShopLiveCommon.setAuthToken(null)
ShopLiveCommon.setUser(null)

// 데이터 객체에 delegate 를 심어 넘깁니다 (재생·프리뷰·리스트 공통)
let data = ShopLiveShortformCollectionData(delegate: self)
ShopLiveShortform.play(requestData: data)

extension MyViewController: ShopLiveShortformReceiveHandlerDelegate {
    // 필요한 것만 구현 — 전부 optional
}

// 핸들러를 먼저 선언합니다
val myHandler = object : ShopLiveShortformHandler() {
    // 필요한 것만 override
}

// ① 데이터/뷰마다 지정 — 이 방식이 기본입니다
val data = ShopLiveShortformCollectionData().apply { handler = myHandler }
binding.shortsCardTypeView.handler = myHandler

// ② 전역 — 하이브리드(WebView) 브리지 경로에서만 읽힙니다
ShopLiveShortform.setHandler(myHandler)

func handleProductItem(shortsId: String, shortsSrn: String, product: ProductData) {
    // product.url · sku · productId · customerProductId 중 앱이 쓰는 키로 라우팅
    guard let urlStr = product.url, let url = URL(string: urlStr) else { return }
    navigationController?.pushViewController(ProductDetailViewController(url: url), animated: true)
}

func handleProductBanner(shortsId: String, shortsSrn: String, scheme: String) {
    // 배너는 콘솔에서 지정한 스킴/URL 이 그대로 넘어옵니다
    openDeepLink(scheme)
}

override fun getOnClickProductListener() = ShopLiveShortformProductListener { context, data, product ->
    // product.url · sku · productId 중 앱이 쓰는 키로 라우팅
    product.url?.takeIf { it.startsWith("http") }?.let { url ->
        ProductDetailActivity.start(context, url)
    }
}

override fun getOnClickBannerListener() = ShopLiveShortformUrlListener { context, data, url ->
    openDeepLink(context, url)
}

func handleShare(shareMetadata: ShopLiveShareMetaData) {
    // title · descriptions · thumbnail · shortsId · shortsSrn
    let link = makeMyDeepLink(shortsId: shareMetadata.shortsId)
    let vc = UIActivityViewController(activityItems: [shareMetadata.title ?? "", link],
                                      applicationActivities: nil)
    // 숏폼은 별도 윈도우 위에 뜨므로, 그 윈도우 기준으로 present 해야 합니다
    ShopLiveShortform.getCurrentKeyWindow()?.rootViewController?.present(vc, animated: true)
}

override fun onShare(context: Context, data: ShopLiveShortformShareData) {
    // shortsId · srn · title · description · thumbnail
    val link = makeMyDeepLink(data.shortsId)
    val send = Intent(Intent.ACTION_SEND).apply {
        type = "text/plain"
        putExtra(Intent.EXTRA_TEXT, "${data.title}\n$link")
    }
    context.startActivity(Intent.createChooser(send, null))
}

func onEvent(messenger: ShopLiveShortformMessenger?, command: String, payload: String?) {
    switch command {
    case "VIDEO_MUTED":              isMuted = true
    case "VIDEO_UNMUTED":            isMuted = false
    case "DETAIL_ON_PLAYER_SHOWN":   analytics.log("shorts_detail_open")
    case "COLLECTION_CLICK_ITEM":    analytics.log("shorts_card_click")
    default:                         break            // 모르는 커맨드는 무시
    }
}

override fun onEvent(
    context: Context,
    messenger: ShopLiveShortformMessageListener?,
    command: String,
    payload: Map<String, Any?>
) {
    when (command) {
        "VIDEO_MUTED"   -> isMuted = true
        "VIDEO_UNMUTED" -> isMuted = false
        else -> Unit                                  // 모르는 커맨드는 무시
    }
}

// 1·2) 첫 페이지 재생
let ids = firstPage.map { ShopLiveShortformIdData(shortsId: $0.id, payload: nil) }
ShopLiveShortform.play(
    shortformIdsData: ShopLiveShortformIdsData(ids: ids, currentId: ids.first?.shortsId),
    dataSourceDelegate: self,
    shortsCollectionDelegate: self
)

// 3) 페이지네이션 — 아래로 / 위로 각각
extension MyFeed: ShortsCollectionViewDataSourcRequestDelegate {
    func onShortformListDownwardPagination(
        completion: @escaping ((ShopLiveShortformIdsMoreData?, Error?)) -> ()
    ) {
        myAPI.next { page, error in
            guard let page = page else { completion((nil, error)); return }
            let more = ShopLiveShortformIdsMoreData(
                ids: page.items.map { ShopLiveShortformIdData(shortsId: $0.id, payload: nil) },
                hasMore: page.hasMore
            )
            completion((more, nil))
        }
    }

    func onShortformListUpwardPagingation(
        completion: @escaping ((ShopLiveShortformIdsMoreData?, Error?)) -> ()
    ) {
        completion((nil, nil))          // 위로 더 불러올 게 없으면 nil
    }
}

// 1·2·3) 재생 + 페이지네이션 (코루틴 버전)
val idsData = ShopLiveShortformIdsData().apply {
    ids = firstPage.map { ShopLiveShortformIdData(it.id) }
    currentId = firstPage.firstOrNull()?.id
    handler = myHandler
}

ShopLiveShortform.play(
    context,
    idsData,
    moreSuspendListener = {                       // 아래로 더 불러오기
        val page = myApi.next()
        ShopLiveShortformIdsMoreData().apply {
            ids = page.items.map { ShopLiveShortformIdData(it.id) }
            hasMore = page.hasMore
        }
    },
    previousSuspendListener = { null }            // 위로 더 불러올 게 없으면 null
)

// 코루틴을 쓰지 않는다면 Future 버전도 있습니다
// ShopLiveShortform.play(context, idsData, moreFutureListener, previousFutureListener)

ShopLiveShortform.setVisibileDetailViews(options: ShopLiveShortformVisibleDetailData(
    isBookMarkVisible: false,
    isShareButtonVisible: true,
    isCommentButtonVisible: false,
    isLikeButtonVisible: true
))

ShopLiveShortform.setVisibleDetailTypeViews(
    ShopLiveShortformVisibleDetailTypeData(
        isBookmarkVisible = false,
        isShareButtonVisible = true,
        isCommentButtonVisible = false,
        isLikeButtonVisible = true
    )
)

ShopLiveShortform.setResizeMode(mode: .CENTER_CROP)   // .FIT | .AUTO

ShopLiveShortform.setResizeMode(ShopLiveResizeMode.CENTER_CROP)   // FIT | AUTO

builder.setVisibleTitle(isVisisble: true)
builder.setVisibleDescription(isVisible: false)
builder.setVisibleBrand(isVisible: true)
builder.setVisibleProductCount(isVisible: true)
builder.setVisibleViewCount(isVisible: false)
builder.setCellSpacing(spacing: 8)
builder.setCellCornerRadius(radius: 16)
builder.setCellBackgroundColor(color: .white)
builder.setCardViewType(type: .type2)
builder.reloadItems()                        // 변경 반영

with(binding.shortsCardTypeView) {
    setVisibleTitle(true)
    setVisibleDescription(false)
    setVisibleBrand(true)
    setVisibleProductCount(true)
    setVisibleViewCount(false)
    setRadius(16f.toPx(context))
    setCardBackgroundColor(Color.WHITE)
    setViewType(ShopLiveShortform.CardViewType.CARD_TYPE2)
    submit()                                 // 변경 반영
}

ShopLiveShortform.get(context, collectionData, object : ShopLiveShortformCollectionListener {
    override fun onData(data: ShopLiveShortformCollectionResponse) {
        binding.shortsHorizontalTypeView.submit(collectionData, data)
    }
    override fun onError(e: Exception) { /* … */ }
})

// iOS 는 동등한 공개 API 가 없습니다.
// 목록만 필요한 경우 고객사 서버에서 Shoplive Open API 로 조회한 뒤
// 미션 6(내 목록으로 재생)의 ID 방식으로 넘기는 구성을 권장합니다.

// 지금 쌓인 캐시를 비웁니다
AVAssetDownloadManager.shared.deleteCaches()

// 앱 종료 시 자동으로 비우도록 설정 (앱 시작 시 1회)
AVAssetDownloadManager.shared.enableDeleteCacheOnTerminate(isEnabled: true)

// Android 는 동등한 공개 캐시 제어 API 가 없습니다.
// 재생 엔진(media3 / ExoPlayer)의 캐시 정책을 따릅니다.

ShopLiveShortform.setReferrer(referrer: "home_banner")      // 전역
// 또는 데이터 생성 시: ShopLiveShortformCollectionData(referrer: "home_banner", …)

ShopLiveCommon.setUtmSource(utmSource: "naver")
ShopLiveCommon.setUtmMedium(utmMedium: "cpc")
ShopLiveCommon.setUtmCampaign(utmCampaign: "spring_sale")
ShopLiveCommon.setUtmContent(utmContent: "banner_a")

val data = ShopLiveShortformCollectionData().apply { referrer = "home_banner" }
// 리스트 뷰: binding.shortsCardTypeView.setReferrer("home_tab")

ShopLiveCommon.setUtmSource("naver")
ShopLiveCommon.setUtmMedium("cpc")
ShopLiveCommon.setUtmCampaign("spring_sale")
ShopLiveCommon.setUtmContent("banner_a")

// 웹뷰 생성 직후 연결
ShopLiveShortform.BridgeInterface.connect(myWebView)

// 숏폼 풀스크린 위에 앱 화면(예: 상품 상세)을 띄울 때
ShopLiveShortform.BridgeInterface.present(viewController: productDetailVC)

// 화면을 벗어날 때
ShopLiveShortform.BridgeInterface.disconnect()

// 웹뷰 생성 직후 브리지를 자바스크립트 인터페이스로 등록
val bridge = ShopLiveShortformBridgeInterface(myWebView, null)
myWebView.addJavascriptInterface(bridge, "ShopLiveBridgeInterface")
bridge.observe(activity)          // ComponentActivity 수명주기에 맞춰 메시지 수신

// 화면을 벗어날 때
bridge.removeObserver()

func onError(error: Error) {
    guard let e = error as? ShopLiveCommonError else { return }
    log("shortform error \(e.codes) \(e.message ?? "")")
    // 9900 대역이면 재시도 UI, 9000 대역이면 개발 중 assert 권장
}

override fun onError(context: Context, error: ShopLiveCommonError) {
    log("shortform error ${error.code} ${error.message}")
    when (error.code) {
        ShopLiveCommonErrorCode.FAILED_NETWORK -> showRetry()
        ShopLiveCommonErrorCode.NOT_INITIALIZED_ACCESS_KEY -> check(false) { "accessKey 미설정" }
        else -> Unit
    }
}