Shoplive ショートフォーム SDK 連携ガイド

// 1) 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")),
]

// 2) CocoaPods — Podfile
// pod 'ShopliveShortformSDK', '1.8.13'
// pod 'ShopliveSDKCommon',    '1.8.13'

// 3) 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)
    // … Auto Layout の制約 …

    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: .female,
    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.FEMALE)
    }
)

// ③ 未ログイン — 呼び出す必要はありません

// ログアウト — ユーザー情報をリセット(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")

// WebView 生成直後に接続
ShopLiveShortform.BridgeInterface.connect(myWebView)

// ショートのフルスクリーンの上にアプリ画面（例: 商品詳細）を表示するとき
ShopLiveShortform.BridgeInterface.present(viewController: productDetailVC)

// 画面を離れるとき
ShopLiveShortform.BridgeInterface.disconnect()

// WebView 生成直後にブリッジを JavaScript インターフェースとして登録
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
    }
}