Shoplive Shortform SDK Integration Guide

// ① 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        // access key, authentication, common models
import ShopLiveShortformSDK     // shorts playback, lists, preview

// settings.gradle / build.gradle — mavenCentral() required
dependencies {
    implementation("cloud.shoplive:shoplive-short-form:1.8.14")   // shorts
    implementation("cloud.shoplive:shoplive-common:1.8.14")       // shared (access key, auth)
    implementation("cloud.shoplive:shoplive-network:1.8.14")      // networking

    // Playback engine — declare <b>only one</b> of these (engine versions are numbered separately from the SDK)
    implementation("cloud.shoplive:shoplive-media3:1.10.1.3")     // media3 (default) — minSdk 23
    // implementation("cloud.shoplive:shoplive-exoplayer:2.19.1.20")  // ExoPlayer (legacy) — minSdk 19
}

android {
    defaultConfig { multiDexEnabled = true }
}

// ① Once at app startup (AppDelegate)
ShopLiveCommon.setAccessKey(accessKey: "YOUR_ACCESS_KEY")

// ② Play — with no query, you get every short
ShopLiveShortform.play(requestData: ShopLiveShortformCollectionData(delegate: nil))

// ① Once at app startup (Application.onCreate)
ShopLiveCommon.setAccessKey("YOUR_ACCESS_KEY")

// ② Play — with no query, you get every short
ShopLiveShortform.play(context)

let data = ShopLiveShortformCollectionData(
    tags: ["spring", "outerwear"],
    tagSearchOperator: .AND,        // match every tag (.OR = match any)
    brands: ["shoplive"],
    shuffle: true,
    skus: ["SKU-1001"],
    shortsCollectionId: "COLLECTION_ID",
    isMuted: false,
    delegate: self                  // receive events — Mission 5
)
ShopLiveShortform.play(requestData: data)

val data = ShopLiveShortformCollectionData().apply {
    tags = listOf("spring", "outerwear")
    tagSearchOperator = ShopLiveShortformTagSearchOperator.AND
    brands = listOf("shoplive")
    shuffle = true
    skus = listOf("SKU-1001")
    shortsCollectionId = "COLLECTION_ID"
    isMuted = false
    handler = myHandler             // receive events — Mission 5
}
ShopLiveShortform.play(context, data)

@IBAction func openShorts() {
    let data = ShopLiveShortformCollectionData(
        tags: ["spring"],
        tagSearchOperator: .AND,
        shuffle: true,
        delegate: self          // optional: receive events
    )
    ShopLiveShortform.play(requestData: data)
}

fun openShorts() {
    val data = ShopLiveShortformCollectionData().apply {
        tags = listOf("spring")
        tagSearchOperator = ShopLiveShortformTagSearchOperator.AND
        shuffle = true
        handler = myHandler     // optional: receive events
    }
    ShopLiveShortform.play(context, data)
}

ShopLiveShortform.close()      // when your app must close it (sign-out, deep link, …)

ShopLiveShortform.close()      // when your app must close it (sign-out, deep link, …)

// iOS — build it, then take the view out with 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,   // product and share events — Mission 5
        enableSnap: false,
        enablePlayVideo: true,
        playOnlyOnWifi: false,
        cellSpacing: 8,
        cellRadius: 16,
        viewCountVisibility: true
    ).getView()

    listView.translatesAutoresizingMaskIntoConstraints = false
    view.addSubview(listView)
    // … Auto Layout constraints …

    builder.setHashTags(tags: ["spring"], tagSearchOperator: .AND)
    builder.submit()                       // ← required once the query is set
    self.builder = builder
}

// Android — place the view in XML, configure it in code, then 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)                                        // grid columns
    setViewType(ShopLiveShortform.CardViewType.CARD_TYPE1)
    handler = myHandler                                    // product and share events — Mission 5
    setHashTags(listOf("spring"), ShopLiveShortformTagSearchOperator.AND)
    submit()                                               // ← required once the query is set
}

// Vertical and horizontal come from ListViewBuilder
let builder = ShopLiveShortform.ListViewBuilder()
let listView = builder.build(
    cardViewType: .type1,
    listViewType: .horizontal,        // .vertical | .horizontal
    playableType: .CENTER,            // which cell plays in a horizontal list
    listViewDelegate: self,
    shortsCollectionDelegate: self
).getView()
builder.submit()

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

// Horizontal — ShopLiveShortformHorizontalTypeView
with(binding.shortsHorizontalTypeView) {
    setViewType(ShopLiveShortform.CardViewType.CARD_TYPE1)
    setPlayableType(ShopLiveShortform.PlayableType.CENTER)
    enableSnap()
    submit()                                     // ← horizontal lists need submit() too
}

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()          // recalculate layout on rotation
}

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

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

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

feed.resultHandler = { result in
    if case .didScrollToShortsId(let shortsId) = result {
        print("current short: \(shortsId ?? "")")
    }
}

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

// res/layout — <cloud.shoplive.sdk.shorts.ShopLiveShortformDetailTypeView … />
with(binding.shortsDetailTypeView) {
    setMuted(false)
    setUIComponentPadding(bottom = bottomNavHeight)   // keep clear of the bottom tab bar
    setHashTags(listOf("spring"), ShopLiveShortformTagSearchOperator.AND)
    submit()                                          // ← always call once the query is set
}

// Forward the system back gesture to the feed
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)

// Dismissing
ShopLiveShortform.close()

ShopLiveShortform.hidePreview()          // dismiss first so you never stack two
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
    }
)

// Dismissing
ShopLiveShortform.hidePreview()
// Is one on screen right now?
if (ShopLiveShortform.isShowingPreview()) { /* … */ }

// ① Signed in · secure auth (recommended) — a JWT signed by your backend (Step 4)
ShopLiveCommon.setAuthToken(authToken: myJwtFromServer)

// ② Signed in · simple — pass the profile directly (unsigned · not for authorization)
ShopLiveCommon.setUser(user: ShopLiveCommonUser(
    userId: hashedUserId,          // a hash, not the raw member ID (Step 3)
    userName: "Jane Doe",
    age: 29,
    gender: .female,
    userScore: 3
))

// ③ Signed out — no call needed

// Sign-out — reset the user info (clears the JWT and profile)
ShopLiveCommon.setAuthToken(authToken: nil)
ShopLiveCommon.setUser(user: nil)

// Current state
let isLoggedIn = ShopLiveCommon.isLoggedIn()

// ① Signed in · secure auth (recommended) — a JWT signed by your backend (Step 4)
ShopLiveCommon.setAuthToken(myJwtFromServer)

// ② Signed in · simple — pass the profile directly (unsigned · not for authorization)
ShopLiveCommon.setUser(
    ShopLiveCommonUser(userId = hashedUserId).apply {   // a hash, not the raw member ID (Step 3)
        setUserName("Jane Doe")
        setAge(29)
        setGender(ShopLiveCommonUserGender.FEMALE)
    }
)

// ③ Signed out — no call needed

// Sign-out — reset the user info (clears the JWT and profile)
ShopLiveCommon.setAuthToken(null)
ShopLiveCommon.setUser(null)

// Put the delegate on the data object (same for playback, preview and lists)
let data = ShopLiveShortformCollectionData(delegate: self)
ShopLiveShortform.play(requestData: data)

extension MyViewController: ShopLiveShortformReceiveHandlerDelegate {
    // Implement only what you need — every method is optional
}

// Declare the handler first
val myHandler = object : ShopLiveShortformHandler() {
    // Override only what you need
}

// ① Per data object / per view — this is the normal way
val data = ShopLiveShortformCollectionData().apply { handler = myHandler }
binding.shortsCardTypeView.handler = myHandler

// ② Global — only read on the hybrid (WebView) bridge path
ShopLiveShortform.setHandler(myHandler)

func handleProductItem(shortsId: String, shortsSrn: String, product: ProductData) {
    // Route on whichever key your app uses: 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) {
    // Banners hand you the scheme or URL configured in the console, as-is
    openDeepLink(scheme)
}

override fun getOnClickProductListener() = ShopLiveShortformProductListener { context, data, product ->
    // Route on whichever key your app uses: 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)
    // Shorts live in their own window — present relative to that window
    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            // ignore commands you don't know
    }
}

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                                  // ignore commands you don't know
    }
}

// 1 and 2) Play the first page
let ids = firstPage.map { ShopLiveShortformIdData(shortsId: $0.id, payload: nil) }
ShopLiveShortform.play(
    shortformIdsData: ShopLiveShortformIdsData(ids: ids, currentId: ids.first?.shortsId),
    dataSourceDelegate: self,
    shortsCollectionDelegate: self
)

// ③ Pagination — downward and upward, separately
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 when there is nothing above
    }
}

// 1, 2 and 3) Playback plus pagination (coroutine flavor)
val idsData = ShopLiveShortformIdsData().apply {
    ids = firstPage.map { ShopLiveShortformIdData(it.id) }
    currentId = firstPage.firstOrNull()?.id
    handler = myHandler
}

ShopLiveShortform.play(
    context,
    idsData,
    moreSuspendListener = {                       // load more, downward
        val page = myApi.next()
        ShopLiveShortformIdsMoreData().apply {
            ids = page.items.map { ShopLiveShortformIdData(it.id) }
            hasMore = page.hasMore
        }
    },
    previousSuspendListener = { null }            // null when there is nothing above
)

// Not using coroutines? There is a Future variant too
// 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()                        // apply the changes

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()                                 // apply the changes
}

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

// iOS has no equivalent public API.
// If you only need the data, query it from your server with the Shoplive Open API
// and feed the IDs in through Mission 6 (play your own list).

// Clear what is cached right now
AVAssetDownloadManager.shared.deleteCaches()

// Or have it cleared automatically on app termination (call once at startup)
AVAssetDownloadManager.shared.enableDeleteCacheOnTerminate(isEnabled: true)

// Android exposes no equivalent public cache-control API.
// It follows the playback engine's cache policy (media3 / ExoPlayer).

ShopLiveShortform.setReferrer(referrer: "home_banner")      // global
// Or at construction: 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" }
// List views: binding.shortsCardTypeView.setReferrer("home_tab")

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

// Connect right after creating the web view
ShopLiveShortform.BridgeInterface.connect(myWebView)

// To show an app screen (e.g. product detail) on top of the shorts full screen
ShopLiveShortform.BridgeInterface.present(viewController: productDetailVC)

// When leaving the screen
ShopLiveShortform.BridgeInterface.disconnect()

// Right after creating the web view, register the bridge as a JavaScript interface
val bridge = ShopLiveShortformBridgeInterface(myWebView, null)
myWebView.addJavascriptInterface(bridge, "ShopLiveBridgeInterface")
bridge.observe(activity)          // receive messages for the ComponentActivity's lifetime

// When leaving the screen
bridge.removeObserver()

func onError(error: Error) {
    guard let e = error as? ShopLiveCommonError else { return }
    log("shortform error \(e.codes) \(e.message ?? "")")
    // 9900s → offer a retry; 9000s → assert during development
}

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) { "access key not set" }
        else -> Unit
    }
}