Shoplive V1 모바일 SDK 연동 가이드

// settings.gradle (dependencyResolutionManagement) 또는 프로젝트 build.gradle
repositories {
    maven { url 'https://sdk.shoplive.cloud/maven-repo' }
    google()
    mavenCentral()
}

// app/build.gradle
dependencies {
    def shoplive_sdk_version = "1.9.0"

    implementation "cloud.shoplive:shoplive-sdk-core:$shoplive_sdk_version"
    implementation "cloud.shoplive:shoplive-common:$shoplive_sdk_version"
    implementation "cloud.shoplive:shoplive-network:$shoplive_sdk_version"
    implementation "cloud.shoplive:shoplive-exoplayer:2.19.1.20"
    // ExoPlayer 대신 Media3 를 쓰려면:
    // implementation "cloud.shoplive:shoplive-media3:1.10.1.3"
}

ShopLive.setHandler(object : ShopLiveHandler() {
    override fun handleNavigation(context: Context, url: String) {
        // 링크 이동 처리
    }
})

flutter pub add 'shoplive_player:^1.9.0'

# pubspec.yaml
dependencies:
  shoplive_player: ^1.9.0

# ios/Podfile (맨 위)
source 'https://github.com/shoplive/pod-specs.git'
source 'https://cdn.cocoapods.org/'
platform :ios, '15.0'

cd ios && pod install --repo-update

// android/build.gradle(.kts)
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://sdk.shoplive.cloud/maven-repo") }
    }
}

import 'package:shoplive_player/shoplive_player.dart';
import 'package:shoplive_player/shoplive_common.dart';

import ShopliveSDKCommon
import ShopLiveSDK

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

// 2) 시청 진입
ShopLive.play(data: .init(campaignKey: "재생할_CAMPAIGN_KEY"))

// 1) 앱 시작 시 1회
ShopLive.setAccessKey("발급받은_ACCESS_KEY")
ShopLive.setHandler(myHandler)

// 2) 시청 진입
ShopLive.play(this, ShopLivePlayerData("재생할_CAMPAIGN_KEY"))

final common = ShopLiveCommon();
final player = ShopLivePlayer();

// 1) 앱 시작 시 1회
common.setAccessKey(accessKey: '발급받은_ACCESS_KEY');

// 2) 시청 진입
player.play(data: ShopLivePlayerData(campaignKey: '재생할_CAMPAIGN_KEY'));

git clone https://github.com/shoplive/shoplive-sdk-flutter.git
cd shoplive-sdk-flutter && git checkout 1.9.0
cd shoplive_flutter_sample/example && flutter pub get && flutter run

import ShopliveSDKCommon
import ShopLiveSDK

ShopLiveCommon.setAccessKey(accessKey: "{ACCESS_KEY}")
ShopLive.play(data: .init(campaignKey: "{CAMPAIGN_KEY}"))

ShopLive.setAccessKey(accessKey)
ShopLive.play(this, ShopLivePlayerData(campaignKey).apply {
    keepWindowStateOnPlayExecuted = false
    referrer = "referrer"
})

final common = ShopLiveCommon();
final player = ShopLivePlayer();

common.setAccessKey(accessKey: "{ACCESS_KEY}");
player.play(data: ShopLivePlayerData(campaignKey: "{CAMPAIGN_KEY}"));

let previewData = ShopLivePreviewData(
    campaignKey: "{CAMPAIGN_KEY}",
    isMuted: true,
    resolution: .PREVIEW
)

ShopLive.preview(data: previewData) {
    // 미리보기를 탭했을 때 본 재생으로 전환하고 싶다면 여기서 play 를 호출합니다
    ShopLive.play(data: .init(campaignKey: "{CAMPAIGN_KEY}"))
}

ShopLive.showPreviewPopup(this@YourActivity, ShopLivePreviewData(campaignKey))

// 1) 옵션을 먼저 설정하고
player.setPreviewOption(
  data: ShopLivePlayerPreviewData(
    campaignKey: "{CAMPAIGN_KEY}",
    useCloseButton: true,
    enableSwipeOut: true,
    position: "BOTTOM_RIGHT",
  ),
);

// 2) 노출한다 (숨길 때는 hidePreview)
player.showPreview(campaignKey: "{CAMPAIGN_KEY}");

<!-- AndroidManifest.xml -->
<activity
    android:name=".SchemeActivity"
    android:exported="true"
    android:noHistory="true"
    android:screenOrientation="portrait">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data
            android:scheme="https"
            android:host="xxxx"
            android:path="/yyyy" />
    </intent-filter>
</activity>

<intent-filter>
    <action android:name="android.intent.action.VIEW" />

    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

    <data
        android:scheme="shoplive"
        android:host="live" />
</intent-filter>

// SceneDelegate
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url,
          let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
          let queryItems = components.queryItems else { return }

    var campaignKey: String? = nil

    for item in queryItems {
        let value = item.value ?? ""
        switch item.name {
        case "ak":           ShopLiveCommon.setAccessKey(accessKey: value)
        case "ck":           campaignKey = value
        case "utm_source":   ShopLiveCommon.setUtmSource(utmSource: value)
        case "utm_medium":   ShopLiveCommon.setUtmMedium(utmMedium: value)
        case "utm_campaign": ShopLiveCommon.setUtmCampaign(utmCampaign: value)
        case "utm_content":  ShopLiveCommon.setUtmContent(utmContent: value)
        default:             ShopLive.addParameter(key: item.name, value: value)
        }
    }

    guard let campaignKey = campaignKey else { return }
    ShopLive.play(data: .init(campaignKey: campaignKey))
}

class SchemeActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        handle(intent)
    }

    override fun onNewIntent(intent: Intent?) {
        super.onNewIntent(intent)
        handle(intent)
    }

    private fun handle(intent: Intent?) {
        val uri = intent?.data
        if (uri == null) {
            finish()
            return
        }

        var campaignKey: String? = null

        for (name in uri.queryParameterNames) {
            val value = uri.getQueryParameter(name) ?: continue
            when (name) {
                "ak" -> ShopLiveCommon.setAccessKey(value)
                "ck" -> campaignKey = value
                "utm_source" -> ShopLive.setUtmSource(value)
                "utm_medium" -> ShopLive.setUtmMedium(value)
                "utm_campaign" -> ShopLive.setUtmCampaign(value)
                "utm_content" -> ShopLive.setUtmContent(value)
                else -> ShopLive.addParameter(name, value)
            }
        }

        // 플레이어 실행은 NEW_TASK 로 띄운 Activity 에 맡긴다 (아래 설명 참고)
        startActivity(Intent(this, MainActivity::class.java).apply {
            flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK
            putExtra("campaignKey", campaignKey)
        })
        finish()
    }
}

final common = ShopLiveCommon();
final player = ShopLivePlayer();

void handleDeepLink(Uri uri) {
  uri.queryParameters.forEach((key, value) {
    switch (key) {
      case 'ak':
        common.setAccessKey(accessKey: value);
        break;
      case 'ck':
        break; // 아래에서 바로 사용
      case 'utm_source':
        common.setUtmSource(utmSource: value);
        break;
      case 'utm_medium':
        common.setUtmMedium(utmMedium: value);
        break;
      case 'utm_campaign':
        common.setUtmCampaign(utmCampaign: value);
        break;
      case 'utm_content':
        common.setUtmContent(utmContent: value);
        break;
      default:
        player.addParameter(key: key, value: value);
    }
  });

  final campaignKey = uri.queryParameters['ck'];
  if (campaignKey != null) {
    player.play(data: ShopLivePlayerData(campaignKey: campaignKey));
  }
}

import ShopLiveSDK
import ShopliveSDKCommon

let user = ShopLiveCommonUser(userId: "{USER_ID}", userName: "{USER_NAME}")
ShopLiveCommon.setUser(user: user)

ShopLive.play(data: .init(campaignKey: "{CAMPAIGN_KEY}"))

val user = ShopLiveCommonUser(userId = "{USER_ID}").apply {
    userName = "{USER_NAME}"
}
ShopLive.setUser(user)

ShopLive.play(this, ShopLivePlayerData(campaignKey))

// common·player 는 미션 1에서 만든 인스턴스를 재사용합니다
final user = ShopLiveCommonUser(userId: "{USER_ID}", userName: "{USER_NAME}");
common.setUser(accessKey: "{ACCESS_KEY}", user: user);

player.play(data: ShopLivePlayerData(campaignKey: "{CAMPAIGN_KEY}"));

let user = ShopLiveCommonUser(
    userId: "{USER_ID}",
    userName: "{USER_NAME}",
    age: 25,
    gender: .male,
    userScore: 80,
    custom: ["grade": "vip"])

ShopLiveCommon.setUser(user: user)
ShopLive.play(data: .init(campaignKey: "{CAMPAIGN_KEY}"))

val user = ShopLiveCommonUser(userId = "{USER_ID}").apply {
    userName = "{USER_NAME}"
    gender = ShopLiveCommonUserGender.MALE
    age = 25
    userScore = 20
}
ShopLive.setUser(user)

final user = ShopLiveCommonUser(
  userId: "{USER_ID}",
  userName: "{USER_NAME}",
  gender: ShopLiveCommonUserGender.MALE,
  userScore: 100,
  age: 25,
  custom: {"key": "value"},
);
common.setUser(accessKey: "{ACCESS_KEY}", user: user);

ShopLiveCommon.setAuthToken(authToken: "{USER_JWT}")
ShopLive.play(data: .init(campaignKey: "{CAMPAIGN_KEY}"))

ShopLiveCommon.setAuthToken("{USER_JWT}")
ShopLive.play(this, ShopLivePlayerData(campaignKey))

common.setAuthToken(userJWT: "{USER_JWT}");
player.play(data: ShopLivePlayerData(campaignKey: "{CAMPAIGN_KEY}"));

func onSetUserName(_ payload: [String: Any]) {
    payload.forEach { key, value in
        print("onSetUserName key: \(key) value: \(value)")
    }
}

override fun onSetUserName(jsonObject: JSONObject) {
    super.onSetUserName(jsonObject)
    Log.d(TAG, "userId=${jsonObject.get("userId")}, userName=${jsonObject.get("userName")}")
}

player.userInfo.listen((data) {
  print("userInfo: ${data.userInfo}");
});

func handleReceivedCommand(_ command: String, data: [String: Any]?) {
    switch command {
    case "LOGIN_REQUIRED":
        // 로그인 화면 이동 → 로그인 성공 시 사용자 정보 재설정 후 플레이어 재실행
        break
    default:
        break
    }
}

override fun onReceivedCommand(context: Context, command: String, data: JSONObject) {
    when (command) {
        "LOGIN_REQUIRED" -> {
            // 로그인 화면 이동 → 로그인 성공 시 사용자 정보 재설정 후 플레이어 재실행
        }
    }
}

player.receivedCommand.listen((data) {
  switch (data.command) {
    case "LOGIN_REQUIRED":
      // 로그인 화면 이동 → 로그인 성공 시 사용자 정보 재설정 후 플레이어 재실행
      break;
    default:
      break;
  }
});

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

// 한 번에 지우기 — JWT · 사용자 · accessKey 를 모두 지운다
ShopLiveCommon.clearAuth()
ShopLiveCommon.setAccessKey(accessKey: "{ACCESS_KEY}")   // 다음 재생 전에 다시 설정

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

// 한 번에 지우기 — 사용자 · JWT 만 지운다 (accessKey 는 유지)
ShopLiveCommon.clearAuth()

// 로그아웃 — 사용자 정보 초기화
common.setAuthToken(userJWT: null);
common.clearAuth();   // Flutter 의 setUser 는 null 을 받지 않는다

let inputFont = UIFont.systemFont(ofSize: 14, weight: .regular)
let sendButtonFont = UIFont.systemFont(ofSize: 14, weight: .medium)

ShopLive.setChatViewFont(inputBoxFont: inputFont, sendButtonFont: sendButtonFont)

val nanumGothic = ResourcesCompat.getFont(requireContext(), R.font.nanumgothic)
ShopLiveCommon.setTextTypeface(nanumGothic)

func handleNavigation(with url: URL) {
    let safari = SFSafariViewController(url: url)
    present(safari, animated: true)
}

override fun handleNavigation(context: Context, url: String) {
    val intent = Intent(this@YourActivity, WebViewActivity::class.java)
    intent.putExtra("url", url)
    startActivity(intent)
}

player.handleNavigation.listen((data) {
  launchUrl(Uri.parse(data.url), mode: LaunchMode.externalApplication);
});

func handleDownloadCoupon(with couponId: String, result: @escaping (ShopLiveCouponResult) -> Void) {
    let couponResult = ShopLiveCouponResult(
        couponId: couponId, success: true,
        message: "Coupon download success!",
        status: .SHOW, alertType: .ALERT)
    result(couponResult)
}

override fun handleDownloadCoupon(
    context: Context,
    couponId: String,
    callback: ShopLiveHandlerCallback
) {
    callback.couponResult(
        isDownloadSuccess = true,
        message = "Coupon download success!",
        couponStatus = ShopLive.CouponPopupStatus.HIDE,
        alertType = ShopLive.CouponPopupResultAlertType.ALERT
    )
}

player.handleDownloadCoupon.listen((data) async {
  await player.sendDownloadCouponResult(
    couponId: data.couponId,
    success: true,
    message: "Coupon download success!",
    popupStatus: "KEEP",
    alertType: "ALERT",
  );
});

func handleCustomAction(with id: String, type: String, payload: Any?, result: @escaping (ShopLiveCustomActionResult) -> Void) {
    let actionResult = ShopLiveCustomActionResult(
        id: id, success: true, message: "success!",
        status: .SHOW, alertType: .ALERT)
    result(actionResult)
}

override fun handleCustomAction(
    context: Context,
    id: String,
    type: String,
    payload: JSONObject,
    callback: ShopLiveHandlerCallback
) {
    callback.customActionResult(
        isSuccess = true,
        message = "success!",
        couponStatus = ShopLive.CouponPopupStatus.HIDE,
        alertType = ShopLive.CouponPopupResultAlertType.ALERT
    )
}

player.handleCustomAction.listen((data) async {
  await player.sendCustomActionResult(
    id: data.id,
    success: true,
    message: "success!",
    popupStatus: "SHOW",
    alertType: "ALERT",
  );
});

// ShopLiveSDKDelegate
func handleReceivedCommand(_ command: String, data: [String: Any]?) {
    switch command {
    case "CLICK_PRODUCT_DETAIL":
        // data: 선택한 상품 정보
        break
    case "CLICK_PRODUCT_CART":
        // data: 장바구니에 담은 상품 정보
        break
    default:
        break
    }
}

// ShopLiveHandler
override fun onReceivedCommand(context: Context, command: String, data: JSONObject) {
    when (command) {
        "CLICK_PRODUCT_DETAIL" -> {
            // data: 선택한 상품 정보
        }
        "CLICK_PRODUCT_CART" -> {
            // data: 장바구니에 담은 상품 정보
        }
    }
}

final player = ShopLivePlayer();

player.receivedCommand.listen((event) {
  switch (event.command) {
    case 'CLICK_PRODUCT_DETAIL':
      // event.data: 선택한 상품 정보
      break;
    case 'CLICK_PRODUCT_CART':
      // event.data: 장바구니에 담은 상품 정보
      break;
  }
});

func handleNavigation(with url: URL) {
    // url: 선택한 상품 또는 배너에 설정된 상세 정보 URL
    print("handleNavigation \(url)")
}

override fun handleNavigation(context: Context, url: String) {
    Log.d(TAG, "handleNavigation url=$url")
}

final player = ShopLivePlayer();

player.handleNavigation.listen((event) {
  debugPrint("handleNavigation : ${event.url}");
});

ShopLive.hookNavigation { url in
    // url: 선택한 상품 또는 배너에 설정된 상세 정보 URL
    print("hookNavigation \(url)")
}

// URI Scheme
let scheme = "{your_scheme}://{your_host}?ak=xxx&ck=yyy"
ShopLive.setShareScheme(scheme, shareDelegate: nil)

// 또는 웹 URL
ShopLive.setShareScheme("https://www.share_link.com/?ak=xxx&ck=yyy", shareDelegate: nil)

// URI Scheme
val scheme = "{your_scheme}://{your_host}?ak=xxx&ck=yyy"
ShopLive.setShareScheme(scheme)

// 또는 웹 URL
ShopLive.setShareScheme("https://www.share_link.com/?ak=xxx&ck=yyy")

final player = ShopLivePlayer();

player.setShareScheme(
  shareSchemeUrl: "{your_scheme}://{your_host}?ak=xxx&ck=yyy",
);

// 1) 공유 데이터를 받을 델리게이트를 지정
ShopLive.setShareScheme(scheme, shareDelegate: self)

// 2) 델리게이트에서 앱의 공유 UI 를 띄운다
extension MainViewController: ShopLivePlayerShareDelegate {
    func handleShare(data: ShopLivePlayerShareData) {
        guard let urlString = data.url, let url = URL(string: urlString) else { return }

        let activityVC = UIActivityViewController(activityItems: [url],
                                                  applicationActivities: nil)
        ShopLive.viewController?.present(activityVC, animated: true, completion: nil)
    }
}

// ShopLiveHandler. 재정의하지 않으면 SDK 가 기본 공유 시트를 띄웁니다
override fun handleShare(context: Context, data: ShopLivePlayerShareData) {
    val inflater = getSystemService(LAYOUT_INFLATER_SERVICE) as LayoutInflater
    val view = inflater.inflate(R.layout.custom_share_dialog, null)

    AlertDialog.Builder(context)
        .setView(view)
        .create()
        .show()
}

// PIP 전체 허용 여부 (앱 내 PIP · OS PIP 공통 전제)
ShopLive.setEnabledPictureInPictureMode(isEnabled: true)

// 크기·위치·모서리·닫기 버튼을 한 번에 지정
let config = ShopLiveInAppPipConfiguration(
    useCloseButton: true,
    pipPosition: .bottomRight,
    enableSwipeOut: true,
    pipSize: ShopLiveInAppPipSize(pipMaxSize: 200),
    pipRadius: 10,
    pipPinPositions: [.topLeft, .topRight, .bottomLeft, .bottomRight],
    closeButtonConfig: ShopLiveCloseButtonConfig(position: .topRight, width: 30, height: 30, offsetX: 3, offsetY: 3, color: .white)
)
ShopLive.setInAppPipConfiguration(config: config)

final player = ShopLivePlayer();

// 앱 내 PIP 와 미리보기 창은 같은 창이라 설정도 같은 호출 하나로 합니다
player.setPreviewOption(
  data: ShopLivePlayerPreviewData(
    campaignKey: '재생할_CAMPAIGN_KEY',
    useCloseButton: true,
    enableSwipeOut: true,
    pipRadius: 10,
    pipMaxSize: 400,
    position: 'BOTTOM_RIGHT',
  ),
);

ShopLive.setEnabledOSPictureInPictureMode(isEnabled: true)

// OS PIP 진입 허용 (기본값 true)
ShopLive.setEnabledPictureInPictureMode(true)

// PIP 창 비율. 지정하지 않으면 9:16
// RATIO_1X1 / RATIO_1X2 / RATIO_2X3 / RATIO_3X4 / RATIO_9X16
ShopLive.setPIPRatio(ShopLivePIPRatio.RATIO_9X16)

ShopLivePermissionManager.request(this, ShopLivePermissionType.DRAW_OVERLAY) { hasPermission ->
    // hasPermission == true 이면 오버레이 권한이 허용된 상태입니다
}

// app/build.gradle
implementation "cloud.shoplive:shoplive-permission:$shoplive_sdk_version"

// 앱 내 PIP 로 전환
ShopLive.startPictureInPicture()

// 전체화면으로 복귀
ShopLive.stopPictureInPicture()

// OS PIP 로 전환. 오버레이 권한 안내 화면이 닫히기를 기다려야 하면 true
ShopLive.startPictureInPicture(shouldDelayForOverlayPermissionFlow = false)

// 전체화면으로 복귀
ShopLive.stopPictureInPicture()

final player = ShopLivePlayer();

player.startPictureInPicture();
player.stopPictureInPicture();

// 화면 가장자리에서 PIP 가 들어오지 못하게 할 영역
let offsetApplied = ShopLive.setPictureInPictureFloatingOffset(
    offset: UIEdgeInsets(top: 60, left: 0, bottom: 90, right: 0))

// PIP 자체에 줄 여백
let paddingApplied = ShopLive.setPictureInPicturePadding(
    padding: UIEdgeInsets(top: 8, left: 8, bottom: 8, right: 8))

let previewData = ShopLivePreviewData(
    campaignKey: "재생할_CAMPAIGN_KEY",
    keepWindowStateOnPlayExecuted: true,
    referrer: nil,
    isMuted: true,
    isEnabledVolumeKey: false,
    resolution: .PREVIEW
)

ShopLive.preview(data: previewData) {
    // 미리보기 창을 탭했을 때 전체화면으로 넘기려면
    ShopLive.play(data: .init(campaignKey: "재생할_CAMPAIGN_KEY"))
}

ShopLive.showPreviewPopup(this, ShopLivePreviewData("재생할_CAMPAIGN_KEY").apply {
    useCloseButton = true
    enabledSwipeOut = true
    resolutionType = ShopLivePreviewResolutionType.LIVE

    onClickListener = View.OnClickListener { view ->
        // 미리보기 → 플레이어 전환 애니메이션
        ShopLive.setPreviewTransitionAnimation(this@MainActivity, view)
        ShopLive.play(this@MainActivity, ShopLivePlayerData("재생할_CAMPAIGN_KEY"))
    }
})

final player = ShopLivePlayer();

// 1) 옵션을 먼저 지정
player.setPreviewOption(
  data: ShopLivePlayerPreviewData(
    campaignKey: '재생할_CAMPAIGN_KEY',
    useCloseButton: true,
    enableSwipeOut: true,
    pipRadius: 10,
    pipMaxSize: 400,
    position: 'BOTTOM_RIGHT',
  ),
);

// 2) 미리보기 시작
player.showPreview(campaignKey: '재생할_CAMPAIGN_KEY');

player.hidePreview();

// 옵션을 한 번 저장. campaignKey 는 showPreviewPopup 호출 값으로 덮어써집니다
ShopLive.setPreviewOptions(ShopLivePreviewData("재생할_CAMPAIGN_KEY").apply {
    useCloseButton = true
    enabledSwipeOut = true
})

// 띄울 때는 campaignKey 만
ShopLive.showPreviewPopup(this, "재생할_CAMPAIGN_KEY")

<cloud.shoplive.sdk.ShopLivePreview
    android:id="@+id/preview"
    android:layout_width="120dp"
    android:layout_height="180dp" />

import ShopLiveSDK
import ShopliveSDKCommon

final class PreviewCell: UITableViewCell {
    private var preview: ShopLivePlayerPreview?

    func configure(campaignKey: String) {
        let preview = ShopLivePlayerPreview()
        preview.translatesAutoresizingMaskIntoConstraints = false
        contentView.addSubview(preview)
        NSLayoutConstraint.activate([
            preview.topAnchor.constraint(equalTo: contentView.topAnchor),
            preview.leadingAnchor.constraint(equalTo: contentView.leadingAnchor),
            preview.widthAnchor.constraint(equalToConstant: 120),
            preview.heightAnchor.constraint(equalToConstant: 180)
        ])
        self.preview = preview

        preview.action(.initialize)
        preview.resultHandler = { result in
            switch result {
            case .didChangeCampaignStatus(let status):
                print(status)
            case .onError(let code, let message):
                print(code, message)
            case .handleReceivedCommand(let command, let payload):
                print(command, payload ?? [:])
            default:
                break   // 그 밖의 케이스는 미리보기 컴포넌트 레퍼런스 참고
            }
        }
        // 전역 accessKey 를 이 값으로 바꾼다
        preview.action(.start(accessKey: "{ACCESS_KEY}", campaignKey: campaignKey, referrer: nil))
    }

    override func prepareForReuse() {
        super.prepareForReuse()
        preview?.action(.close)   // 셀 재사용 시 정리 — 부모 뷰에서 제거한다
        preview = nil
    }
}

// owner 는 어댑터 생성자로 받아 둔 LifecycleOwner(호스트 Activity/Fragment)입니다
class PreviewAdapter(
    private val owner: LifecycleOwner,
    private val campaignKeys: List<String>,
) : RecyclerView.Adapter<PreviewAdapter.ViewHolder>() {

    override fun getItemCount() = campaignKeys.size

    override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): ViewHolder {
        val view = LayoutInflater.from(parent.context)
            .inflate(R.layout.item_preview, parent, false)
        return ViewHolder(view)
    }

    override fun onBindViewHolder(holder: ViewHolder, position: Int) {
        holder.onBind(campaignKeys[position])
    }

    // RecyclerView 가 셀을 붙이고 뗄 때 재생을 시작·해제합니다
    override fun onViewAttachedToWindow(holder: ViewHolder) {
        super.onViewAttachedToWindow(holder)
        holder.onViewAttachedToWindow()
    }

    override fun onViewDetachedFromWindow(holder: ViewHolder) {
        holder.onViewDetachedFromWindow()
        super.onViewDetachedFromWindow(holder)
    }

    inner class ViewHolder(view: View) : RecyclerView.ViewHolder(view) {
        private val preview: ShopLivePreview = view.findViewById(R.id.preview)

        fun onBind(campaignKey: String) {
            preview.initializePlayer()
            preview.setLifecycleObserver(owner)
            preview.campaignKey = campaignKey
            preview.setMuted(true)
        }

        fun onViewAttachedToWindow() {
            preview.start() // 미션 1에서 ShopLiveCommon.setAccessKey 로 이미 설정한 accessKey 를 씁니다
        }

        fun onViewDetachedFromWindow() {
            preview.release()
        }
    }
}

import ShopliveSDKCommon

let products = [
    ShopLiveConversionProductData(
        productId: "productId",
        customerProductId: "customerProductId",
        sku: "sku",
        url: "url",
        purchaseQuantity: 1,
        purchaseUnitPrice: 1000.0)
]

ShopLiveEvent.sendConversionEvent(data: .init(
    type: "purchase",
    products: products,
    orderId: "orderId",
    referrer: "referrer",
    custom: ["campaignKey": "campaignKey"]))

ShopLiveEvent.sendConversionEvent(
    ShopLiveConversionData(
        "purchase",
        products = listOf(
            ShopLiveConversionProductData(
                productId = "productId",
                customerProductId = "customerProductId",
                sku = "sku",
                url = "url",
                purchaseQuantity = 1,
                purchaseUnitPrice = 1000.0,
            )
        ),
        orderId = "orderId",
        referrer = "referrer",
        custom = mapOf("campaignKey" to "campaignKey"),
    )
)

// 로그인 사용자: 시청할 때와 같은 방식
ShopLiveCommon.setUser(user: ShopLiveCommonUser(userId: "{USER_ID}"))
// 또는 백엔드가 서명한 JWT
ShopLiveCommon.setAuthToken(authToken: "{USER_JWT}")

// 비로그인: 앱이 관리하는 기기 식별값이 있을 때만
ShopLiveCommon.setAnonId(anonId: "{DEVICE_ID}")

// 로그인 사용자: 시청할 때와 같은 방식
ShopLive.setUser(ShopLiveCommonUser(userId = "{USER_ID}"))
// 또는 백엔드가 서명한 JWT
ShopLiveCommon.setAuthToken("{USER_JWT}")

// 비로그인: 앱이 관리하는 기기 식별값이 있을 때만
ShopLiveCommon.setAnonId("{DEVICE_ID}")

// ShopLiveSDKDelegate
private var isMuted = false

func onEvent(name: String, feature: ShopLiveLog.Feature, campaign: String, payload: [String: Any]) {
    switch name {
    case "video_muted":
        isMuted = true
    case "video_unmuted":
        isMuted = false
    default:
        break
    }
}

// ShopLiveHandler
private var isMuted = false

override fun onEvent(context: Context, data: ShopLiveLog.Data) {
    when (data.name) {
        "video_muted" -> isMuted = true
        "video_unmuted" -> isMuted = false
    }
}

final player = ShopLivePlayer();
bool isMuted = false;

player.log.listen((data) {
  switch (data.name) {
    case "video_muted":
      isMuted = true;
      break;
    case "video_unmuted":
      isMuted = false;
      break;
  }
});

ShopLive.setMuteWhenPlayStart(isMuted)
ShopLive.play(data: .init(campaignKey: "{CAMPAIGN_KEY}"))

ShopLive.setMuteWhenPlayStart(isMuted)
ShopLive.play(this, ShopLivePlayerData("{CAMPAIGN_KEY}"))

final player = ShopLivePlayer();

player.setMuteWhenPlayStart(isMute: isMuted);
player.play(data: ShopLivePlayerData(campaignKey: "{CAMPAIGN_KEY}"));

// 위 표의 값 중 하나를 넣습니다 (.PIP · .KEEP · .CLOSE)
ShopLive.setNextActionOnHandleNavigation(actionType: .PIP)

// 위 표의 값 중 하나를 넣습니다 (PIP · KEEP · CLOSE)
ShopLive.setNextActionOnHandleNavigation(ActionType.PIP)

ShopLive.sendCommandMessage(
    command: "SET_BRAND_FAVORITE",
    payload: ["identifier": "brand-identifier", "favorite": true])

ShopLive.sendCommandMessage(
    "SET_BRAND_FAVORITE",
    mapOf("identifier" to "brand-identifier", "favorite" to true)
)

func handleReceivedCommand(_ command: String, data: [String: Any]?) {
    switch command {
    case "ON_CLICK_BRAND_FAVORITE_BUTTON":
        guard let identifier = data?["identifier"] as? String else {
            return
        }
        // 앱·백엔드에서 팔로우를 처리하고, 확정된 최종 상태를 그대로 보냅니다
        updateFavorite(identifier: identifier) { isFavorite in
            ShopLive.sendCommandMessage(
                command: "SET_BRAND_FAVORITE",
                payload: ["identifier": identifier, "favorite": isFavorite])
        }
    case "ON_CHANGED_BRAND_FAVORITE":
        // 팔로우 상태가 바뀐 결과를 알려줍니다
        break
    default:
        break
    }
}

override fun onReceivedCommand(context: Context, command: String, data: JSONObject) {
    when (command) {
        "ON_CLICK_BRAND_FAVORITE_BUTTON" -> {
            val identifier = data.getString("identifier")
            // 앱·백엔드에서 팔로우를 처리하고, 확정된 최종 상태를 그대로 보냅니다
            updateFavorite(identifier) { isFavorite ->
                ShopLive.sendCommandMessage(
                    "SET_BRAND_FAVORITE",
                    mapOf("identifier" to identifier, "favorite" to isFavorite)
                )
            }
        }
        "ON_CHANGED_BRAND_FAVORITE" -> {
            // 팔로우 상태가 바뀐 결과를 알려줍니다
            val identifier = data.getString("identifier")
        }
    }
}

let configuration = WKWebViewConfiguration()
configuration.allowsInlineMediaPlayback = true
let webView = WKWebView(frame: view.bounds, configuration: configuration)

webView.webViewClient = object : WebViewClient() {
    override fun shouldOverrideUrlLoading(
        view: WebView?,
        request: WebResourceRequest?
    ): Boolean {
        // 별도 스킴이 있을 때만 여기서 처리합니다
        val url = request?.url ?: return super.shouldOverrideUrlLoading(view, request)
        if (url.toString().startsWith("market")) {
            val intent = Intent(Intent.ACTION_VIEW).apply {
                data = url
            }
            startActivity(intent)
            return true
        }
        return super.shouldOverrideUrlLoading(view, request)
    }
}

webView.webChromeClient = object : WebChromeClient() {
    override fun onCreateWindow(
        view: WebView?,
        isDialog: Boolean,
        isUserGesture: Boolean,
        resultMsg: Message?
    ): Boolean {
        view ?: return true
        resultMsg ?: return true
        val subWebView = WebView(view.context)
        subWebView.webViewClient = object : WebViewClient() {
            // API 23 이하 단말을 지원한다면 String 오버로드도 함께 구현해야 합니다
            override fun shouldOverrideUrlLoading(view: WebView?, url: String?): Boolean {
                url ?: return false
                if (url.startsWith("http")) {
                    webView.loadUrl(url)
                }
                return true
            }
            override fun shouldOverrideUrlLoading(
                view: WebView?,
                request: WebResourceRequest?
            ): Boolean {
                val url = request?.url?.toString() ?: return false
                if (url.startsWith("http")) {
                    webView.loadUrl(url)
                }
                return true
            }
        }
        val viewTransport = (resultMsg.obj as? WebView.WebViewTransport) ?: return true
        viewTransport.webView = subWebView
        resultMsg.sendToTarget()
        return true
    }
}

val intent = Intent(Intent.ACTION_VIEW).apply {
    data = Uri.parse(url)
}
startActivity(intent)

ShopLive.indicatorColor = UIColor.purple

ShopLive.setLoadingProgressColor(Color.RED)

var images: [UIImage] = []

for i in 1...11 {
    images.append(.init(named: "loading\(i)")!)
}

ShopLive.setLoadingAnimation(images: images)

ShopLive.setLoadingAnimation(R.drawable.progress_animation)

<?xml version="1.0" encoding="utf-8"?>
<animation-list xmlns:android="http://schemas.android.com/apk/res/android"
    android:oneshot="false">

    <item android:drawable="@drawable/loading1" android:duration="100" />
    <item android:drawable="@drawable/loading2" android:duration="100" />
    <item android:drawable="@drawable/loading3" android:duration="100" />
    <item android:drawable="@drawable/loading4" android:duration="100" />
</animation-list>

// 이어폰이 빠져도 계속 재생 (기본값 false, 즉 정지)
ShopLive.setKeepPlayVideoOnHeadphoneUnplugged(true)
// 계속 재생하되 음소거로
ShopLive.setKeepPlayVideoOnHeadphoneUnplugged(true, isMute: true)
print(ShopLive.isKeepPlayVideoOnHeadPhoneUnplugged())

// 통화가 끝나면 자동으로 다시 재생 (iOS 기본값 false, 즉 멈춘 채 유지)
ShopLive.setAutoResumeVideoOnCallEnded(true)
print(ShopLive.isAutoResumeVideoOnCallEnded())

// 이어폰이 빠져도 계속 재생 (기본값 false, 즉 정지)
ShopLive.setKeepPlayVideoOnHeadphoneUnplugged(true, false)
// 계속 재생하되 음소거로
ShopLive.setKeepPlayVideoOnHeadphoneUnplugged(true, true)

// 통화가 끝나면 자동으로 다시 재생 (Android 기본값 true)
ShopLive.setAutoResumeVideoOnCallEnded(false)

handleNavigation(with url: URL)

handleNavigation(context, url: String)

handleNavigation → {url}

handleDownloadCoupon(with couponId: String, result: (ShopLiveCouponResult) -> Void)

handleDownloadCoupon(context, couponId: String, callback: ShopLiveHandlerCallback)

handleDownloadCoupon → {couponId}

handleCustomAction(with id: String, type: String, payload: Any?, result: (ShopLiveCustomActionResult) -> Void)

handleCustomAction(context, id: String, type: String, payload: JSONObject, callback: ShopLiveHandlerCallback)

handleCustomAction → {id, type, payload: String}

handleChangeCampaignStatus(status: String)

onChangeCampaignStatus(context, campaignStatus: String)

changeCampaignStatus → {campaignStatus}

handleCampaignInfo(campaignInfo: [String: Any])

onCampaignInfo(campaignInfo: JSONObject)

campaignInfo → {campaignInfo: Map}

handleChangedPlayerStatus(status: String)

onChangedPlayerStatus(isPipMode: Boolean, playerLifecycle: PlayerLifecycle)

changedPlayerStatus

onSetUserName(_ payload: [String: Any])

onSetUserName(jsonObject: JSONObject)

userInfo → {userInfo: Map}

handleError(code: String, message: String)

onError(context, error: ShopLiveCommonError)

error → {code, message}

handleReceivedCommand(_ command: String, data: [String: Any]?)

onReceivedCommand(context, command: String, data: JSONObject)

receivedCommand → {command, data: Map}

handleCommand(_ command: String, with payload: Any?)

playerPanGesture(state: UIGestureRecognizer.State, position: CGPoint)

handlePreviewTouchGesture()

onEvent(name: String, feature: ShopLiveLog.Feature, campaign: String, payload: [String: Any])

onEvent(context, data: ShopLiveLog.Data)

log → {name, feature, campaignKey, payload: Map}

ShopLivePlayerShareDelegate.handleShare(data: ShopLivePlayerShareData)

handleShare(context, data: ShopLivePlayerShareData)

onUserCloseAction(isPipMode: Boolean)

ShopLive.setCloseHandler(_ handler: (ShopLiveViewHiddenActionType) -> Void)
ShopLive.setPreviewCloseHandler(_ handler: (ShopLiveViewHiddenActionType) -> Void)

onClose(type: ShopLivePresentType, reason: ShopLiveViewHiddenActionType)

previewClose → ShopLivePreviewClose {campaignKey, reason}

ShopLivePlayerPreviewDelegate.handlePlaybackEvent(_ event: ShopLivePreviewPlaybackEvent)

ShopLivePreview.setOnPlaybackEventListener(OnPlaybackEventListener)

// 쿠폰 결과. handleDownloadCoupon 의 result 로 넘긴다
ShopLiveCouponResult(couponId: String,
                     success: Bool,
                     message: String?,
                     status: ShopLiveResultStatus,      // SHOW / HIDE / KEEP
                     alertType: ShopLiveResultAlertType) // ALERT / TOAST

// 커스텀 액션 결과. handleCustomAction 의 result 로 넘긴다
ShopLiveCustomActionResult(id: String,
                           success: Bool,
                           message: String?,
                           status: ShopLiveResultStatus,
                           alertType: ShopLiveResultAlertType)

// 두 콜백 모두 SDK 가 건네준 callback 객체에 담는다
callback.couponResult(
    isDownloadSuccess = true,
    message = successMessage,
    couponStatus = ShopLive.CouponPopupStatus.HIDE,          // SHOW / HIDE / KEEP
    alertType = ShopLive.CouponPopupResultAlertType.TOAST    // ALERT / TOAST
)

callback.customActionResult(
    isSuccess = true,
    message = successMessage,
    couponStatus = ShopLive.CouponPopupStatus.HIDE,
    alertType = ShopLive.CouponPopupResultAlertType.ALERT
)

// Flutter 만 스트림이 아니라 별도 메서드로 결과를 보낸다
await ShopLivePlayer().sendDownloadCouponResult(
  couponId: couponId,
  success: true,
  message: successMessage,
  popupStatus: "HIDE",   // SHOW / HIDE / KEEP
  alertType: "TOAST",    // ALERT / TOAST
);

await ShopLivePlayer().sendCustomActionResult(
  id: id,
  success: true,
  message: successMessage,
  popupStatus: "HIDE",
  alertType: "ALERT",
);

// 레거시. 사용자 정보. 대체: ShopLiveCommon.setUser(user:accessKey:). 생성자 파라미터 레이블은 userName: (원문 name: 은 컴파일 안 됨) · 미션 3
ShopLive.user: ShopLiveCommonUser?

// 레거시. 사용자 정보 JWT(보안 인증). 대체: ShopLiveCommon.setAuthToken(authToken:) · 미션 3
ShopLive.authToken: String?

// 레거시(v2 에서 제거 예정). with accessKey: String 하나로 AccessKey 설정. 대체: ShopLiveCommon.setAccessKey(accessKey:)
ShopLive.configure

// setAuthToken 으로 넣은 JWT 조회. 없으면 setUser 로 생성된 JWT · 미션 3
ShopLiveCommon.getAuthToken() -> String?

// 사용자 정보 설정(accessKey 는 이미 설정된 값을 그대로 사용). accessKey 를 함께 지정하려면 ShopLiveCommon.setUser(accessKey, user) · 미션 3
ShopLive.setUser(user: ShopLiveCommonUser?)

// 레거시. ShopLiveUser 타입은 더 이상 쓰지 않습니다. 대체: 위 ShopLiveCommonUser 버전
ShopLive.setUser(user: ShopLiveUser)

// 사용자 정보 JWT 설정(보안 인증) · 미션 3
ShopLive.setAuthToken(authToken: String)

// 위 설정값 조회 · 미션 3
ShopLive.getAuthToken(): String?

// 레거시. AccessKey 설정. 대체: ShopLive.setAccessKey(accessKey:)
ShopLive.configure(accessKey: String)

// 앱 내 PIP·OS PIP 진입을 통틀어 허용할지 여부(끄면 플레이어 이탈 시 자동 PIP 전환도 안 됨) · 기본값 true · 미션 8
setEnabledPictureInPictureMode(isEnabled: Bool)

// 앱 내 PIP 의 크기·위치·닫기 버튼 모양을 세부 설정(닫기 버튼 표시는 config.useCloseButton 프로퍼티로 지정하며, 레거시 useCloseButton(_:) 을 대체. 닫기 버튼 모양 = closeButtonConfig). 이전 개별 설정 API 들보다 우선 적용됨 · 미션 8
setInAppPipConfiguration(config: ShopLiveInAppPipConfiguration)

// 주어진 PIP 설정·영상비로 실제 렌더 크기를 계산
getPreviewSize(inAppPipConfiguration: ShopLiveInAppPipConfiguration, videoRatio: CGSize) -> CGSize

// Preview 화면 위에 커스텀 뷰를 얹음(닫기 버튼은 별도로 꺼야 함)
addSubViewToPreview(subView: UIView)

// 전체화면 → 앱 내 PIP 로 전환 · 기본값 scale 0.4 · 미션 8
startPictureInPicture(with position: ShopLive.PipPosition, scale: CGFloat) / startPictureInPicture()

// PIP → 전체화면으로 전환 · 미션 8
stopPictureInPicture()

// OS PIP 로 나갔다 앱으로 돌아올 때 마지막 재생 상태(PIP/전체화면)를 유지할지, 항상 전체화면으로 돌릴지 · 기본값 false(항상 전체화면) · 미션 8
setKeepWindowStyleOnReturnFromOsPip(_ keep: Bool)

// 위 설정값 조회 · 미션 8
isKeepWindowStyleOnReturnFromOsPip() -> Bool

// OS PIP 만 별도로 허용할지 여부(앱 내 PIP 는 이 설정과 무관) · 기본값 true · 미션 8
setEnabledOSPictureInPictureMode(isEnabled: Bool)

// 앱 내 PIP 가 이동할 수 있는 영역의 상하좌우 패딩. 값이 유효하지 않으면 false 를 반환하고 기본값 적용 · 기본값 top/left/right/bottom 20 · 미션 8
setPictureInPicturePadding(padding: UIEdgeInsets) -> Bool

// 앱 내 PIP 가 이동 가능한 영역 자체를 오프셋으로 제한. 값이 유효하지 않으면 false 반환 · 미션 8
setPictureInPictureFloatingOffset(offset: UIEdgeInsets) -> Bool

// 레거시. Preview·PIP 모드에서 닫기 버튼 표시 여부. 대체: setInAppPipConfiguration(config:) 의 useCloseButton 프로퍼티
useCloseButton(_ use: Bool)

// 플레이어 이탈 시 자동으로 PIP 로 전환할지 여부 · 미션 8
ShopLive.setEnabledPictureInPictureMode(isEnabled: Boolean)

// PIP 화면 시작 시 기본 화면 배율(RATIO_1X1 / 1X2 / 2X3 / 3X4 / 9X16) · 미션 8
ShopLive.setPIPRatio(pipRatio: ShopLivePIPRatio)

// 뒤로 가기로 화면을 나갈 때 종료 대신 PIP 로 전환할지 여부 · 미션 8
ShopLive.setEnterPipModeOnBackPressed(isEnterPipMode: Boolean)

// 전체화면 → PIP 전환. 레거시 무인자형 startPictureInPicture() 는 deprecated(이 시그니처로 shouldDelayForOverlayPermissionFlow = false 호출됨) · 미션 8
ShopLive.startPictureInPicture(shouldDelayForOverlayPermissionFlow: Boolean)

// PIP → 전체화면 전환 · 미션 8
ShopLive.stopPictureInPicture()

// 뒤로 가기로 화면을 나갈 때 종료 대신 PIP 로 전환할지 여부 · 미션 8
ShopLivePlayer().setEnterPipModeOnBackPressed(isEnterPipMode: bool)

// 전체화면 ↔ PIP 전환 · 미션 8
ShopLivePlayer().startPictureInPicture() / stopPictureInPicture()

// Preview·PIP 모드에서 닫기 버튼 표시 여부
ShopLivePlayer().useCloseButton(canUse: bool)

// 공유 팝업에 전달할 scheme/URL 지정. shareDelegate 를 넘기면 시스템 공유 대신 커스텀 공유 UI 를 직접 구현 · 미션 7
setShareScheme(_ scheme: String?, shareDelegate: ShopLivePlayerShareDelegate?)

// 상품·배너 선택 시 URL 하나만 클로저로 가로챈다. 등록하면 handleNavigation 델리게이트는 호출되지 않음(iOS 전용) · 미션 6
hookNavigation(navigation: @escaping (URL) -> Void)

// 상품·배너 링크 선택 후 플레이어의 다음 동작(PIP/KEEP/CLOSE) 지정 · 기본값 PIP · 미션 11
setNextActionOnHandleNavigation(actionType: ActionType)

// 위 설정값 조회 · 미션 11
getNextActionTypeOnHandleNavigation() -> ActionType

// 공유 팝업에 전달할 scheme/URL 지정 · 미션 7
ShopLive.setShareScheme(shareSchemeUrl: String?)

// 상품·배너 링크 선택 후 플레이어의 다음 동작(PIP/KEEP/CLOSE) 지정 · 미션 11
ShopLive.setNextActionOnHandleNavigation(type: ActionType)

// 공유 시 전달할 scheme/URL 지정 · 미션 7
ShopLivePlayer().setShareScheme(shareSchemeUrl: String)

// 상품·배너 링크 선택 후 다음 동작(show/hide/keep) 지정. 네이티브에는 문자열로 전달되는데 Android 수신부가 정수로 읽어 실제로는 무시된다(미션 11 참고) · 미션 11
ShopLivePlayer().setNextActionOnHandleNavigation(type: ShopLiveActionType)

// 채팅 입력창·전송 버튼 폰트 지정 · 기본값 시스템 폰트 · 미션 4
setChatViewFont(inputBoxFont: UIFont?, sendButtonFont: UIFont?)

// 영상 로딩 진행률을 이미지 시퀀스 애니메이션으로 표시
setLoadingAnimation(images: [UIImage])

// 일반 addSubview 로는 ShopLive 정책상 추가되지 않는 뷰를 강제로 얹음
playerWindow?.forceAddSubView(_:)

// 전체화면 재생 중 상태바 숨김/표시 (InAppPip 에서는 항상 자동으로 보임) · 기본값 true(보이기)
setVisibleStatusBar(isVisible: Bool)

// 로딩 인디케이터 색상 지정 · 미션 11
indicatorColor: UIColor

// 영상 종횡비 유지 방식 지정
setResizeMode(mode: ShopLiveResizeMode)

// 로딩 프로그레스 바 색상 지정 · 미션 11
ShopLive.setLoadingProgressColor(@ColorInt colorInt: Int)

// 로딩 프로그레스 바를 이미지 애니메이션으로 지정(0 이면 해제) · 미션 11
ShopLive.setLoadingAnimation(@DrawableRes drawableRes: Int)

// 채팅 입력창·전송 버튼 폰트를 공통으로 지정 · 미션 4
ShopLive.setChatViewTypeface(typeface: Typeface?)

// 화면의 상태바 숨김/표시 · 기본값 false(숨김)
ShopLive.setVisibleStatusBar(isVisible: Boolean)

// 상태바·내비게이션 바 색상 변경. play 전에 호출. ShopLivePlayerSystemBarColorData(statusBarColor · navigationBarColor 기본 검정 DEFAULT_COLOR, isTaskBarOpened 기본 false)
ShopLive.setSystemBarColor(data: ShopLivePlayerSystemBarColorData)

// 위 색상 설정을 기본값으로 되돌림. play 전에 호출
ShopLive.clearSystemBarColor()

// 플레이어 화면 위에 커스텀 DialogFragment 표시·종료
ShopLive.showDialogFragment(dialogFragment: DialogFragment?) / closeDialogFragment()

// 방송 화면 스크린샷 허용 여부
ShopLive.setPlayerScreenCaptureEnabled(isEnabled: Boolean)

// 영상 종횡비 유지 방식 지정 · 기본값 CENTER_CROP
ShopLive.setResizeMode(resizeMode: ShopLiveResizeMode)

// 영상 종횡비 유지 방식 지정
ShopLivePlayer().setResizeMode(mode: ShopLiveResizeMode)

// 통화 종료 후 영상으로 돌아왔을 때 자동 재생할지 설정 · 기본값 false(자동 재생 안 함) · 미션 11
setAutoResumeVideoOnCallEnded(_ autoResume: Bool)

// 위 설정값 조회 · 미션 11
isAutoResumeVideoOnCallEnded() -> Bool

// 이어폰(헤드셋) 연결이 끊겼을 때 재생을 계속할지(keepPlay, 필수 인자), 계속한다면 음소거로 처리할지(isMute). 호출하지 않으면 SDK 기본 동작은 정지 · 기본값 isMute 기본값 false · 미션 11
setKeepPlayVideoOnHeadphoneUnplugged(_ keepPlay: Bool, isMute: Bool = false)

// 위 설정값 조회 · 미션 11
isKeepPlayVideoOnHeadPhoneUnplugged() -> Bool

// 플레이어 시작 시 음소거 여부 · 기본값 false(사운드 켜짐) · 미션 11
setMuteWhenPlayStart(_ mute: Bool)

// 다른 앱 오디오와 함께 재생할지, 외부 오디오 재생 시 일시정지할지 · 기본값 true(함께 재생)
setMixWithOthers(isMixAudio: Bool)

// AVAudioSession.Category 직접 지정(iOS 전용 오디오 세션 제어)
setAudioSessionCategory(category: AVAudioSession.Category)

// 이어폰(헤드셋) 연결이 끊겼을 때 계속 재생할지(isKeep), 계속한다면 음소거로 처리할지(isMute). 두 인자 모두 필수이고 1인자 형태는 없음. 끊김은 ACTION_AUDIO_BECOMING_NOISY 로 감지해 권한 불필요(Android 12 이상 실기기 요확인) · 미션 11
ShopLive.setKeepPlayVideoOnHeadphoneUnplugged(isKeep: Boolean, isMute: Boolean)

// 통화 종료 후 영상 자동 재생 여부. READ_PHONE_STATE 권한 필요 · 미션 11
ShopLive.setAutoResumeVideoOnCallEnded(isAutoResume: Boolean)

// 플레이어 시작 시 음소거 여부 · 기본값 false(사운드 켜짐) · 미션 11
ShopLive.setMuteWhenPlayStart(isMuted: Boolean)

// 오디오 포커스를 다른 앱에 뺏겼을 때(전화 등) 이벤트를 직접 받아 처리. OnAudioFocusListener 는 onGain() · onLoss() 두 메서드
ShopLive.setSoundFocusHandling(listener: OnAudioFocusListener?)

// 다른 앱 오디오와 함께 재생할지, 외부 오디오 재생 시 일시정지할지 · 기본값 true(함께 재생)
ShopLive.setMixWithOthers(isMixAudio: Boolean)

// 플레이어 시작 시 음소거 여부 · 미션 11
ShopLivePlayer().setMuteWhenPlayStart(isMute: bool)

// 다른 앱 오디오와 함께 재생할지, 외부 오디오 재생 시 일시정지할지
ShopLivePlayer().setMixWithOthers(isMixAudio: bool)

// 서버로 사전 정의된 command·payload 전달(예: 플레이어 위 토스트 표시)
// 토스트는 command "SHOW_LAYER_TOAST", payload 키 message(필수) · duration(ms) · position(TOP/BOTTOM/CENTER) — 이전 문서 근거 · 요확인
sendCommandMessage(command: String, payload: [String:Any]?)

// 로컬 스토리지 저장 기능 사용 여부
setUsingLocalStorage(_ use: Bool)

// 앱 버전 전달(호출하지 않아도 SDK 가 자동으로 읽어 서버에 전달)
setAppVersion(_ appVersion: String)

// 플레이어 실행 전 커스텀 데이터(key-value) 추가·삭제
addParameter(key: String, value: String) / removeParameter(key: String)

// UTM 파라미터를 데이터 인사이트에 함께 전달
setUtmSource(utmSource: String?) / setUtmMedium(utmMedium: String?) / setUtmCampaign(utmCampaign: String?) / setUtmContent(utmContent: String?)

// 서버로 사전 정의된 command·payload 전달
// 토스트는 command "SHOW_LAYER_TOAST", payload 키 message(필수) · duration(ms) · position(TOP/BOTTOM/CENTER) — 이전 문서 근거 · 요확인
ShopLive.sendCommandMessage(command: String?, payload: Map<String, Any?>)

// 앱 버전 전달(호출하지 않아도 SDK 가 자동으로 읽어 서버에 전달)
ShopLive.setAppVersion(appVersion: String)

// UTM 파라미터를 데이터 인사이트에 함께 전달
ShopLive.setUtmSource / setUtmMedium / setUtmCampaign / setUtmContent(String?)

// 플레이어 실행 전 커스텀 데이터(key-value) 추가·삭제
ShopLive.addParameter(key: String, value: String?) / removeParameter(key: String)

// Shoplive 기본 Web Landing 페이지 대신 지정한 URL 사용(사전 협의 필요)
ShopLive.setEndpoint(endpoint: String?)

// 지정한 URL 을 Web Landing 페이지로 사용(사전 협의 필요)
ShopLivePlayer().setEndpoint(endpoint: String?)

// 플레이어 실행 전 커스텀 데이터(key-value) 추가·삭제
ShopLivePlayer().addParameter(key: String, value: String?) / removeParameter(key: String)

// 서버로 사전 정의된 command·payload 전달
ShopLivePlayer().sendCommandMessage(command: String, payload: Map<String, dynamic>)

// UTM 파라미터를 데이터 인사이트에 함께 전달
ShopLiveCommon().setUtmSource / setUtmMedium / setUtmCampaign / setUtmContent(String?)

// 현재 플레이어 스타일 조회 (fullScreen / pip / unknown)
style: ShopLive.PresentationStyle

// 현재 플레이어 모드 조회 (play / preview / none)
playerMode: ShopLive.PlayerMode

// 현재 재생 중인 방송의 영상 비율 조회 (portrait / landscape / unknown)
orientationMode: ShopLive.VideoOrientation

// 플레이어가 표시 중인 UIWindow 인스턴스
playerWindow: ShopliveWindow?

// 플레이어가 표시 중인 UIViewController 인스턴스 (Alert 등을 present 할 때 사용)
viewController: ShopLiveViewController?

// 방송 진입 성공 여부 확인. handleReceivedCommand 로 ON_SUCCESS_CAMPAIGN_JOIN 이 온 뒤부터 true
isSuccessCampaignJoin() -> Bool

// 시청 중인 방송 종료
ShopLive.close()

// 루트 액티비티 종료 시 방송도 함께 종료할지 여부. false 면 앱 종료 시점에 직접 close() 호출 필요 · 기본값 true(함께 종료)
ShopLive.setAutoCloseWhenAppDestroyed(isAutoClosed: Boolean)

// 현재 화면 상태 조회 (None / InAppPIP / PIP / Full)
ShopLive.getStatus(): Status

// 미리보기 팝업 표시 중 여부
ShopLive.isShowingPreviewPopup(): Boolean

// 방송 진입 성공 여부 확인. 플레이어가 ON_SUCCESS_CAMPAIGN_JOIN 커맨드를 보낸 뒤부터 true
ShopLive.isSuccessCampaignJoin(): Boolean

// (선택) SDK 캐시 크기 조회 · 삭제. 둘 다 @WorkerThread 라 백그라운드에서 호출. SDK 가 마지막 Activity 파기 시 자동 정리하므로 보통은 부를 필요 없음
ShopLiveCommon.getCacheDirectoryBytes(context: Context): Long
ShopLiveCommon.deleteCacheFiles(ShopLiveCommon.getCacheDirectory(context)): Boolean

// 시청 중인 방송 종료
ShopLivePlayer().close()

import ShopLiveSDK
import ShopliveSDKCommon   // 요청·응답 타입을 직접 쓸 때 필요

let request = ShopLiveCampaignListRequest(page: 1, size: 20, statuses: [.onair, .ready], order: .descending)

// 콜백은 메인 스레드에서 정확히 한 번 온다
let task = ShopLive.API.getCampaigns(request) { result in
    switch result {
    case .success(let response):
        for campaign in response.campaigns {
            if case .onair = campaign.lifecycle.status {
                print(campaign.campaignKey, campaign.title ?? "")
            }
            // showUserCount 가 false 면 시청자 수를 보여주지 않는다
            if let metrics = campaign.metrics, metrics.showUserCount {
                print(metrics.userCount ?? 0)
            }
        }
        print(response.hasMore)   // true 면 page 를 1 올려 다시 요청
    case .failure(let error):
        print(error.codes)        // 9000 · 서버 코드 · 9900 · 9901
    }
}
// 화면을 벗어날 때 task.cancel() 을 부른다

// iOS 13 이상 async 판. Task 를 취소하면 요청도 취소되고 CancellationError 를 던진다
let response = try await ShopLive.API.getCampaigns(ShopLiveCampaignListRequest(statuses: [.onair]))

val request = ShopLiveCampaignListRequest(
    page = 1,
    size = 20,
    statuses = listOf(ShopLiveCampaignFilterStatus.ONAIR, ShopLiveCampaignFilterStatus.READY),
    order = ShopLiveCampaignOrder.DESCENDING,
)

// 콜백은 메인 스레드에서 정확히 한 번 온다
val handle = ShopLiveCampaigns.getCampaigns(request, object : ShopLiveCampaignListListener {
    override fun onData(response: ShopLiveCampaignListResponse) {
        response.campaigns.forEach { campaign ->
            if (campaign.lifecycle.status == ShopLiveCampaignStatus.OnAir) {
                Log.d("Shoplive", campaign.campaignKey)
            }
            // showUserCount 가 false 면 시청자 수를 보여주지 않는다
            val metrics = campaign.metrics
            if (metrics != null && metrics.showUserCount) {
                Log.d("Shoplive", "${metrics.userCount}")
            }
        }
        // hasMore 가 true 면 page 를 1 올려 다시 요청
    }

    override fun onError(error: ShopLiveCommonError) {
        Log.e("Shoplive", "${error.code}")   // 9000 · 서버 코드 · 9900 · 9901 · 10000
    }
})
// 화면을 벗어날 때 handle.cancel() 을 부른다. 취소하면 어떤 콜백도 오지 않는다

// campaignKey 로 방송 영상 재생 시작. ShopLivePlayerData 의 keepWindowStateOnPlayExecuted(기본 true, 실행 모드 유지)·referrer·campaignHandler·brandHandler·isEnabledVolumeKey 로 세부 동작 조정 · 미션 1
play(data: ShopLivePlayerData)

// campaignKey 로 미리보기 재생. campaignKey·referrer·campaignHandler·brandHandler·isEnabledVolumeKey 는 항상 적용되지만, isMuted·resolution(.LIVE/.PREVIEW, 기본 .PREVIEW)은 data 인자가 실제로 ShopLivePreviewData 타입일 때만 적용된다(ShopLivePlayerData 를 그대로 넘기면 무시됨). keepWindowStateOnPlayExecuted 는 이 경로에서 읽지 않는다(play 전용) · 미션 9
preview(data: ShopLivePlayerData, completion: (() -> Void)?)

// 시청 중인 방송 종료
close()

// Android SDK 사용을 위한 AccessKey 설정 · 미션 1
ShopLive.setAccessKey(accessKey: String)

// campaignKey 로 방송 영상 재생. keepWindowStateOnPlayExecuted(기본 true)·referrer 로 세부 동작 조정. intentPlay 는 Intent 객체만 만들어 반환(직접 startActivity 하고 싶을 때) · 미션 1
ShopLive.play(context: Context, data: ShopLivePlayerData) / ShopLive.intentPlay(...): Intent

// campaignKey 로 팝업형 미리보기 표시. ShopLivePreviewData 로 크기·마진·음소거·닫기버튼·스와이프 종료 등을 세부 조정 · 미션 9
ShopLive.showPreviewPopup(activity: Activity, data: ShopLivePreviewData)

// ShopLivePreviewData.useCustomAction 사용 시, 미리보기를 누른 화면 전환에 transitionAnimation 적용
ShopLive.setPreviewTransitionAnimation(activity: Activity, view: View?)

// 재생 중인 팝업형 미리보기 숨김
ShopLive.hidePreviewPopup()

// campaignKey 로 방송 영상 재생 시작 · 미션 1
ShopLivePlayer().play(data: ShopLivePlayerData)

// campaignKey 로 미리보기 표시 · 미션 9
ShopLivePlayer().showPreview(campaignKey: String)

// 미리보기 표시 옵션 지정 · 미션 9
ShopLivePlayer().setPreviewOption(data: ShopLivePlayerPreviewData)

// 표시 중인 미리보기 숨김
ShopLivePlayer().hidePreview()

// 현재 재생 중인 영상 음소거
mute()

// 현재 재생 중인 영상 음소거 해제
unmute()

// 플레이어 음소거
ShopLive.mute()

// 플레이어 음소거 해제
ShopLive.unmute()

// ShopLivePlayerPreview 상태 초기화(campaignKey, campaignId, resizeMode, useCloseButton 등) · 미션 9
preview.action(.initialize)

// accessKey·campaignKey 주입 후 플레이어 로딩. 전역 accessKey 를 이 값으로 바꾼다 · 미션 9
preview.action(.start(accessKey:campaignKey:referrer:))

// 음소거 상태 설정 · 미션 9
preview.action(.setMuted(Bool))

// 추적용 식별자 주입 · 미션 9
preview.action(.setReferrer(String?))

// 재생 / 정지 / 정지+초기화 · 미션 9
preview.action(.play) / .pause / .stop

// 부모 뷰에서 제거하고 메모리 해제 시작 · 미션 9
preview.action(.close)

// 방송 다시 실행 · 미션 9
preview.action(.retry)

// 모서리 반경 설정 · 미션 9
preview.action(.setCornerRadius(CGFloat))

// 닫기 버튼 사용 여부. 1.9.0 에서 동작 없음(닫기 버튼 미지원)
preview.action(.useCloseButton(Bool))

// 디바이스 볼륨 버튼으로 음소거 해제 허용 여부 · 미션 9
preview.action(.setEnabledVolumeKey(isEnabledVolumeKey: Bool))

// 영상 종횡비 유지 방식 · 기본값 CENTER_CROP · 미션 9
preview.action(.setResizeMode(ShopLiveResizeMode))

// 미리보기 해상도(.LIVE/.PREVIEW) · 기본값 .PREVIEW · 미션 9
preview.action(.setResolutionType(ShopLivePlayerPreviewResolution))

// 이벤트를 구독하는 클로저 (Result) -> (). 케이스: log · handleReceivedCommand · avPlayerTimeControlStatus · avPlayerItemStatus · requestShowAlertController · didChangeCampaignStatus · onError · handleCommand · onSetUserName · handleShare · didChangeCampaignInfo · didChangeVideoDimension · handleShopLivePlayerCampaign · handleShopLivePlayerBrand · 미션 9
preview.resultHandler

// 재생 상태 이벤트(ready · playing · paused · buffering · failed)를 받는 델리게이트(ShopLivePlayerPreviewDelegate, weak)
preview.delegate

// 재생 중 여부 / 음소거 여부 / AVPlayerItem 상태 / campaignKey·재생 상태·음소거·재생 시간·캠페인·브랜드 정보 조회
preview.isPlaying() / preview.isMuted() / preview.getPlayerItemStatus() / preview.getPlaybackInfo()

// 레이아웃 XML 에 직접 배치하는 미리보기 컴포넌트 · 미션 9
<cloud.shoplive.sdk.ShopLivePreview>

// 방송 key·referrer를 미리 설정 · 미션 9
setCampaignKey(campaignKey: String?) / setReferrer(referrer: String?)

// 미리보기 플레이어 초기 설정 · 미션 9
initializePlayer()

// 미리보기 재생 시작(내부적으로 initializePlayer→prepare→play 순서로 실행) · 미션 9
start() / start(accessKey:campaignKey:referrer:)

// 미리보기 영상 준비 / 재생 / 일시정지 / 정지 · 미션 9
prepare() / play() / pause() / stop()

// 미리보기 리소스 해제 · 미션 9
release()

// 미리보기 다시 실행 · 미션 9
retry()

// 음소거 상태 전환 · 미션 9
setMuted(isMuted: Boolean)

// 영상 종횡비 유지 방식 · 기본값 CENTER_CROP · 미션 9
setResizeMode(resizeMode: ShopLiveResizeMode)

// LifecycleOwner 등록 시 라이프사이클에 맞춰 자동 play/pause · 미션 9
setLifecycleObserver(owner: LifecycleOwner)

// 미리보기 시작·첫 프레임 렌더·클릭·종료·화면비 변경·재생 상태 변경 이벤트 리스너 등록
setOnInitializeListener / setOnRenderedFirstFrameListener / setOnClickListener / setOnCloseListener / setOnDimensionRatioListener / setOnPlaybackStateChanged

// 닫기 버튼 사용 여부 · 미션 9
useCloseButton(use: Boolean)

// 디바이스 볼륨 버튼으로 음소거 해제 허용 여부 · 미션 9
setEnabledVolumeKey(isEnabledVolumeKey: Boolean)

// 미리보기 해상도(LIVE/PREVIEW) · 기본값 PREVIEW · 미션 9
setResolutionType(resolutionType: ShopLivePreviewResolutionType)

// 미리보기 종료 후 이미지 표시 여부 · 기본값 true
setPostCampaignImageVisible(isPostCampaignImageVisible: Boolean)

// 미리보기 메모리 해제 · 미션 9
destroy()

// campaignKey·재생 상태·음소거·재생 시간·캠페인·브랜드 정보를 한 번에 조회
getPlaybackInfo(): ShopLivePreviewPlaybackInfo