Shoplive SDK 연동 가이드

// Xcode ▸ File ▸ Add Package Dependencies…
// https://github.com/shoplive/shoplive-sdk-ios   (Dependency Rule: Up to Next Major — 3.0.3)

// 타깃에는 필요한 라이브러리만 추가하고, 쓰는 것만 import 합니다.
import ShoplivePlayerSDK     // 시청 — 미션 1~7
import ShopliveStreamerSDK   // 송출 — 미션 8 (송출을 붙일 때만)

// 공통(인증 · 설정 · 사용자)인 ShopliveCore 는 위 SDK 가 함께 가져옵니다.
// Shoplive.initialize · setUser 를 써도 따로 import 하지 않습니다.

// settings.gradle.kts — Shoplive Maven 저장소 추가
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://sdk.shoplive.cloud/maven-repo") }
    }
}

// app/build.gradle.kts
dependencies {
    implementation("cloud.shoplive:shoplive-player-sdk:3.0.3")     // 시청
    implementation("cloud.shoplive:shoplive-streamer-sdk:3.0.3")   // 송출
    // core 는 위 SDK가 자동으로 끌어옵니다
}

# pubspec.yaml — Flutter 3.22 이상 · Dart 3.4 이상
dependencies:
  shoplive_player: 3.0.3     # 시청 (shoplive_core 포함)
  shoplive_streamer: 3.0.3   # 송출 — 필요할 때만

# ios/Podfile — iOS SDK 는 iOS 15 이상 (pod install 때 프레임워크를 내려받습니다)
platform :ios, "15.0"
# Android: Shoplive Maven 저장소는 플러그인이 자동으로 추가합니다

// 1) 앱 시작 시 1회
Shoplive.initialize(.init(accessKey: "발급받은_ACCESS_KEY"))
// 2) 사용자 식별 — 로그인 사용자만 (비로그인이면 생략, 미션 3)
Shoplive.setUser(.token(jwt: myJwt))
// 3) 재생
let player = ShoplivePlayerViewController(campaignKey: "재생할_CAMPAIGN_KEY")
present(player, animated: true)

// 1) 앱 시작 시 1회
Shoplive.initialize(context, ShopliveConfiguration("발급받은_ACCESS_KEY"))
// 2) 사용자 식별 — 로그인 사용자만 (비로그인이면 생략, 미션 3)
Shoplive.setUser(ShopliveUser.Token(myJwt))
// 3) 재생 (인스턴스 생성 즉시 시작)
ShoplivePlayer(context).start(campaignKey = "재생할_CAMPAIGN_KEY")

import "package:shoplive_player/shoplive_player.dart";

// 1) 앱 시작 시 1회
await Shoplive.initialize(const ShopliveConfiguration(accessKey: "YOUR_ACCESS_KEY"));
// 2) 사용자 식별 — 로그인한 사용자만 (게스트는 생략, 미션 3)
await Shoplive.setUser(ShopliveUser.token(myJwt));
// 3) 재생
await ShoplivePlayer.instance.start("YOUR_CAMPAIGN_KEY");

Shoplive.initialize(.init(accessKey: "발급받은_ACCESS_KEY"))
Shoplive.setStreamToken(streamerJwt)          // 송출 전용 토큰 (필수)

let studio = ShopliveStreamerViewController(campaignKey: "송출할_CAMPAIGN_KEY")
present(studio, animated: true)

Shoplive.initialize(context, ShopliveConfiguration("발급받은_ACCESS_KEY"))
Shoplive.setStreamToken(streamerJwt)          // 송출 전용 토큰 (필수)

ShopliveStreamer(context).start(campaignKey = "송출할_CAMPAIGN_KEY")

import "package:shoplive_streamer/shoplive_streamer.dart";

await Shoplive.initialize(const ShopliveConfiguration(accessKey: "YOUR_ACCESS_KEY"));
await Shoplive.setStreamToken(streamerJwt);   // 송출 전용 토큰 (필수)

await ShopliveStreamer.instance.start("YOUR_CAMPAIGN_KEY");

@IBAction func watchLive() {
    let player = ShoplivePlayerViewController(campaignKey: "재생할_CAMPAIGN_KEY")
    player.delegate = self               // 선택: 이벤트 수신
    present(player, animated: true)
}

fun watchLive() {
    ShoplivePlayer(context).apply {
        delegate = myDelegate            // 선택: 이벤트 수신
    }.start(campaignKey = "재생할_CAMPAIGN_KEY")
}

Future<void> watchLive() async {
  final player = ShoplivePlayer.instance;
  player.events.listen(onPlayerEvent);   // 선택: 이벤트 받기 (미션 6)
  await player.start("YOUR_CAMPAIGN_KEY");
}

// SceneDelegate
func scene(_ scene: UIScene, openURLContexts ctxs: Set<UIOpenURLContext>) {
    guard let url = ctxs.first?.url,
          let comps = URLComponents(url: url, resolvingAgainstBaseURL: false),
          let key = comps.queryItems?.first(where: { $0.name == "campaign" })?.value
    else { return }

    let referrer = comps.queryItems?.first(where: { $0.name == "ref" })?.value
    let player = ShoplivePlayerViewController(
        campaignKey: key,
        options: .init(referrer: referrer))
    topViewController?.present(player, animated: true)
}

// 딥링크 수신 Activity
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    val data: Uri? = intent?.data           // myapp://live?campaign=XXXX
    val key = data?.getQueryParameter("campaign") ?: return
    val ref = data.getQueryParameter("ref")

    ShoplivePlayer(this).start(
        campaignKey = key,
        options = ShoplivePlayOptions(referrer = ref))
}

// 앱이 받은 딥링크 URI 로 부릅니다 (예: app_links · go_router)
Future<void> openLive(Uri uri) async {
  final key = uri.queryParameters["campaign"];   // myapp://live?campaign=XXXX
  if (key == null) return;
  final ref = uri.queryParameters["ref"];

  await ShoplivePlayer.instance.start(key,
      playOptions: ShoplivePlayOptions(referrer: ref));
}

// ① 로그인 · 보안 인증 (권장) — 백엔드가 서명한 JWT (4단계)
Shoplive.setUser(.token(jwt: myJwt))

// ② 로그인 · 심플 인증 — 프로필 직접 전달 (SDK 가 서명 없는 JWT 를 만든다)
Shoplive.setUser(.profile(
    id: hashedUserId,            // 원문 대신 해시 권장 (3단계)
    name: "라이브팬", age: 27, gender: .female,
    rank: 10))                    // 사용자 등급 (-100 ~ 100)

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

// 로그아웃 — 사용자 정보(JWT·프로필)를 지우고 송출 토큰도 함께 지운다 (accessKey·게스트 식별자·UTM 은 유지)
Shoplive.logout()

// ① 로그인 · 보안 인증 (권장) — 백엔드가 서명한 JWT (4단계)
Shoplive.setUser(ShopliveUser.Token(myJwt))

// ② 로그인 · 심플 인증 — 프로필 직접 전달 (SDK 가 서명 없는 JWT 를 만든다)
Shoplive.setUser(ShopliveUser.Profile(
    id = hashedUserId,           // 원문 대신 해시 권장 (3단계)
    name = "라이브팬", age = 27, gender = ShopliveGender.FEMALE,
    rank = 10))                    // 사용자 등급 (-100 ~ 100)

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

// 로그아웃 — 사용자 정보(JWT·프로필)를 지우고 송출 토큰도 함께 지운다 (accessKey·게스트 식별자·UTM 은 유지)
Shoplive.logout()

// ① 로그인 · 보안 인증 (권장) — 백엔드가 서명한 JWT (4단계)
await Shoplive.setUser(ShopliveUser.token(myJwt));

// ② 로그인 · 간편 인증 — 프로필을 직접 전달 (SDK 가 서명 없는 JWT 생성)
await Shoplive.setUser(ShopliveUser.profile(
    id: hashedUserId,            // 원본 ID 대신 해시 권장 (3단계)
    name: "LiveFan", age: 27, gender: ShopliveGender.female,
    rank: 10));                    // 사용자 등급 (-100~100)

// ③ 비로그인 — 호출하지 않음

// 로그아웃 — 사용자 정보·토큰 정리
await Shoplive.logout();

// 프리뷰 프리셋 — 낮은 해상도(type = .preview) · 무음 · 오버레이 숨김 · in-App PIP 정책을 한 번에
let playerView = ShoplivePlayerView(configuration: .preview)
container.addSubview(playerView)       // 오토레이아웃은 호스트 앱 자유
playerView.delegate = self
playerView.play(campaignKey: "재생할_CAMPAIGN_KEY")

val playerView = ShoplivePlayerView(context)   // XML/Compose(AndroidView) 배치 자유
// 프리뷰 프리셋 — 낮은 해상도(PREVIEW) · 무음 · 오버레이 숨김 · in-App PIP 정책을 한 번에
playerView.configuration = ShoplivePlayerConfiguration.PREVIEW
container.addView(playerView)

playerView.delegate = myDelegate
playerView.bindLifecycle(viewLifecycleOwner)   // pause/resume/release 자동화
playerView.play(campaignKey = "재생할_CAMPAIGN_KEY")

// Flutter 3.0.3 에도 피드에 넣을 위젯이 없습니다 (ShoplivePlayerView 없음).
// 대안: 프리뷰 스트림을 작은 인앱 PIP 창으로 시작
await ShoplivePlayer.instance.start("YOUR_CAMPAIGN_KEY",
    playOptions: const ShoplivePlayOptions(presentationStyle: ShoplivePresentationStyle.pip),
    configuration: const ShoplivePlayerConfiguration(
        type: ShoplivePlayerType.preview,                            // 프리뷰 스트림 (저해상도)
        sound: ShopliveSoundOptions(muteOnStart: true),              // 음소거로 시작
        overlay: ShopliveOverlayOptions(ui: ShopliveOverlayUIMode.hidden),   // 오버레이 숨김
        pip: ShoplivePipOptions(isInAppPipEnabled: true)));          // presentationStyle: pip 에 필요

playerView.stop()                      // 프리뷰는 멈추고
let player = ShoplivePlayerViewController(campaignKey: "재생할_CAMPAIGN_KEY")   // 본 해상도로 새로 연다
present(player, animated: true)

playerView.stop()                      // 프리뷰는 멈추고
ShoplivePlayer(context).start(campaignKey = "재생할_CAMPAIGN_KEY")   // 기본 type = LIVE

// 본 해상도로 본 시청 전환 — iOS 는 열린 세션에서 그대로 전환
await ShoplivePlayer.instance.start("YOUR_CAMPAIGN_KEY",
    configuration: const ShoplivePlayerConfiguration(type: ShoplivePlayerType.live));

let configuration = WKWebViewConfiguration()
configuration.allowsInlineMediaPlayback = true
configuration.userContentController.add(self, name: "ShopLiveAppInterface")   // WKWebView 생성 전(이 configuration 으로 만들기 전)에 등록
let webView = WKWebView(frame: .zero, configuration: configuration)

// WKScriptMessageHandler
func userContentController(_ controller: WKUserContentController,
                           didReceive message: WKScriptMessage) {
    guard message.name == "ShopLiveAppInterface",
          let campaignKey = message.body as? String else { return }
    playLive(campaignKey)   // 3단계 · 네이티브 재생
}

webView.addJavascriptInterface(ShopLiveAppInterface(activity), "ShopLiveAppInterface")

class ShopLiveAppInterface(private val activity: Activity) {
    @JavascriptInterface                     // 백그라운드 스레드에서 불린다
    fun postMessage(campaignKey: String) {
        activity.runOnUiThread { playLive(activity, campaignKey) }   // 3단계 · 네이티브 재생
    }
}

// webview_flutter — 페이지에 window.ShopLiveAppInterface.postMessage 를 노출
controller.addJavaScriptChannel(
  "ShopLiveAppInterface",
  onMessageReceived: (JavaScriptMessage message) {
    playLive(message.message);   // 3단계 · 네이티브 재생
  },
);

func playLive(_ campaignKey: String) {
    let player = ShoplivePlayerViewController(campaignKey: campaignKey)
    present(player, animated: true)
}

fun playLive(context: Context, campaignKey: String) {
    ShoplivePlayer(context).start(campaignKey = campaignKey)
}

Future<void> playLive(String campaignKey) =>
    ShoplivePlayer.instance.start(campaignKey);

// 로그인 사용자 — 재생 직전에 (미션 3)
Shoplive.setUser(.token(jwt: jwt))
// 이어서 3단계처럼 재생

// 로그인 사용자 — 재생 직전에 (미션 3)
Shoplive.setUser(ShopliveUser.Token(jwt))
// 이어서 3단계처럼 재생

// 로그인 사용자 — 재생 직전에 (미션 3)
await Shoplive.setUser(ShopliveUser.token(jwt));
// 이어서 3단계처럼 재생

player.enterPictureInPicture()      // 작은 창으로
player.exitPictureInPicture()       // 원래대로
if player.isInPictureInPicture { /* … */ }

// 위치·배율 등은 설정으로
var cfg = ShoplivePlayerConfiguration()
cfg.pip.defaultPosition = .bottomRight
cfg.pip.scale = 0.4
cfg.pip.isOSPipEnabled = true

player.enterPictureInPicture()      // 작은 창으로
player.exitPictureInPicture()       // 원래대로
if (player.isInPictureInPicture) { /* … */ }

// 위치·배율 등은 설정으로
val cfg = ShoplivePlayerConfiguration(
    pip = ShoplivePlayerConfiguration.PipOptions(
        defaultPosition = ShoplivePipPosition.BOTTOM_RIGHT,
        scale = 0.4f,
        isOSPipEnabled = true))     // OS PIP 는 Activity 방식 전용

final player = ShoplivePlayer.instance;
await player.enterPictureInPicture();   // 작은 창으로
await player.exitPictureInPicture();    // 원래 화면으로
if (await player.isInPictureInPicture()) { /* … */ }

// 위치·크기 등은 설정으로 (현재 설정 위에 병합)
await player.setConfiguration(const ShoplivePlayerConfiguration(
    pip: ShoplivePipOptions(
        defaultPosition: ShoplivePipPosition.bottomRight,
        scale: 0.4,
        isOSPipEnabled: true)));   // Android: 호스트 Activity 에 android:supportsPictureInPicture="true" 도 추가

var options = ShoplivePlayOptions()
options.presentationStyle = .pip            // 기본값 .fullScreen

player.play(campaignKey: key, options: options)

ShoplivePlayer(this).start(
    campaignKey = key,
    options = ShoplivePlayOptions(
        presentationStyle = ShoplivePlayerPresentationStyle.PIP))   // 기본값 FULLSCREEN

await ShoplivePlayer.instance.start(key,
    playOptions: const ShoplivePlayOptions(
        presentationStyle: ShoplivePresentationStyle.pip));   // 기본은 fullscreen — pip.isInAppPipEnabled 가 꺼져 있으면 INVALID_ARGUMENT

player.configuration = .preview                     // 무음 · 오버레이 숨김 · in-App PIP
player.play(campaignKey: key, options: .preview)    // presentationStyle = .pip

// 프리셋을 출발점으로 고쳐 쓰기 (값 타입이라 복사됨)
var cfg = ShoplivePlayerConfiguration.preview
cfg.pip.defaultPosition = .bottomLeft

ShoplivePlayer(this).start(
    campaignKey = key,
    options = ShoplivePlayOptions(presentationStyle = ShoplivePlayerPresentationStyle.PIP),
    configuration = ShoplivePlayerConfiguration(
        sound = ShoplivePlayerConfiguration.SoundOptions(muteOnStart = true),             // 무음
        overlay = ShoplivePlayerConfiguration.OverlayOptions(ui = ShopliveOverlayUIMode.HIDDEN)))  // 오버레이 숨김

// Flutter 에는 프리셋이 없습니다 — 같은 값을 직접 설정
await ShoplivePlayer.instance.start(key,
    playOptions: const ShoplivePlayOptions(presentationStyle: ShoplivePresentationStyle.pip),
    configuration: const ShoplivePlayerConfiguration(
        sound: ShopliveSoundOptions(muteOnStart: true),                       // 음소거
        overlay: ShopliveOverlayOptions(ui: ShopliveOverlayUIMode.hidden)));   // 오버레이 숨김

extension MyViewController: ShoplivePlayerDelegate {

  // 통지 — 전 케이스. 필요한 case만 남기고 지워도 됩니다
  func player(_ p: ShoplivePlayerControlling, didReceive event: ShoplivePlayerEvent) {
    switch event {
    case .stateChanged(let s):              // 재생 수명주기 (.inAppPIP 진입/복귀 포함)
        print("state:", s)
    case .campaignStatusChanged(let c):     // .ready / .live / .ended
        liveBadge.isHidden = (c != .live)
    case .campaignInfoReceived(let info):   // 캠페인 메타데이터 수신 (제목·브랜드 등)
        titleLabel.text = info.title
    case .playback(let pb):                 // pb.event: .started / .rendering / .rebufferingStarted / .rebufferingEnded / .ended …
        if pb.event == .rebufferingStarted { spinner.isHidden = false }
        if pb.event == .rebufferingEnded { spinner.isHidden = true }
    case .connectionStateChanged(let cs):   // 공통 연결 상태
        networkBanner.isHidden = (cs != .reconnecting)
    case .userNameUpdateRequested(let payload):  // 닉네임 변경 요청 → 앱 프로필 화면
        openProfileEditor(payload)
    case .analytics(let info):              // 시청 통계 → 자체 애널리틱스로 전달
        tracker.log(info.campaignKey, info.isPlaying, info.durationMs)
    case .error(let e):                     // 복구 불가 오류만 전달됨
        show(e.message)
    case .webCommand(let name, let payload):  // 오버레이(웹)가 보낸 커스텀 커맨드 — 예: 로그인 요청
        handleWebCommand(name, payload)
    }
  }

  func player(_ p: ShoplivePlayerControlling, didRequest request: ShoplivePlayerRequest) {
    switch request {
    case .navigation(let url):  router.open(url)      // 상품/배너 랜딩
    case .coupon(let id, let respond):            // 발급 처리 후 결과 회신 — status: 팝업 처리(.show/.hide/.keep), alertType: .alert/.toast
        respond(ShopliveCouponResult(couponId: id, success: true, status: .hide, alertType: .toast))
    case .customWebAction(let id, _, _, let respond):  // 동작 수행 후 결과 회신
        respond(ShopliveCustomActionResult(id: id, success: true, status: .keep, alertType: .toast))
    }
  }
}

val myDelegate = object : ShoplivePlayerDelegate {

  // 통지 — 전 케이스. 필요한 case만 남기고 지워도 됩니다 (기본 구현 empty)
  override fun onEvent(p: ShoplivePlayerControlling, event: ShoplivePlayerEvent) {
    when (event) {
      is ShoplivePlayerEvent.StateChanged ->             // 재생 수명주기 (IN_APP_PIP 진입/복귀 포함)
          log(event.state)
      is ShoplivePlayerEvent.CampaignStatusChanged ->    // READY / LIVE / ENDED
          liveBadge.isVisible = event.status == ShopliveCampaignStatus.LIVE
      is ShoplivePlayerEvent.CampaignInfoReceived ->     // 캠페인 메타데이터 수신 (제목·브랜드 등)
          titleView.text = event.info.title
      is ShoplivePlayerEvent.Playback -> when (event.event) {  // event.event: Started / Rendering / RebufferingStarted / RebufferingEnded / Ended …
          is ShoplivePlaybackEvent.RebufferingStarted -> spinner.isVisible = true
          is ShoplivePlaybackEvent.RebufferingEnded -> spinner.isVisible = false
          else -> Unit
      }
      is ShoplivePlayerEvent.ConnectionStateChanged ->   // 공통 연결 상태
          networkBanner.isVisible = event.state == ShopliveConnectionState.RECONNECTING
      is ShoplivePlayerEvent.UserNameUpdateRequested ->  // 닉네임 변경 요청 → 앱 프로필 화면
          openProfileEditor(event.payload)
      is ShoplivePlayerEvent.Analytics ->                // 시청 통계 → 자체 애널리틱스로 전달
          tracker.log(event.info.campaignKey, event.info.isPlaying, event.info.durationMs)
      is ShoplivePlayerEvent.Error ->                    // 복구 불가 오류만 전달됨
          show(event.error.message)
      is ShoplivePlayerEvent.WebCommandReceived ->      // 오버레이(웹)가 보낸 커스텀 커맨드 — 예: 로그인 요청
          handleWebCommand(event.name, event.payload)
    }
  }

  override fun onRequest(p: ShoplivePlayerControlling, request: ShoplivePlayerRequest) {
    when (request) {
      is ShoplivePlayerRequest.Navigation -> router.open(request.url)
      is ShoplivePlayerRequest.Coupon ->             // 발급 처리 후 결과 회신 — status: 팝업 처리(SHOW/HIDE/KEEP), alertType: ALERT/TOAST
          request.respond(ShopliveCouponResult(couponId = request.id, success = true,
              status = ShopliveResultStatus.HIDE, alertType = ShopliveResultAlertType.TOAST))
      is ShoplivePlayerRequest.CustomWebAction ->    // 동작 수행 후 결과 회신
          request.respond(ShopliveCustomActionResult(id = request.id, success = true,
              status = ShopliveResultStatus.KEEP, alertType = ShopliveResultAlertType.TOAST))
    }
  }
}

final player = ShoplivePlayer.instance;

// 알림 — events 스트림. 필요한 case 만 남겨도 됩니다
player.events.listen((event) {
  switch (event) {
    case ShoplivePlayerStateChanged(:final state):          // 재생 생애주기 (inAppPip 진입·해제 포함)
      log(state);
    case ShopliveCampaignStatusChanged(:final status):      // ready / live / ended
      showLiveBadge(status == ShopliveCampaignStatus.live);
    case ShopliveCampaignInfoReceived(:final info):         // 방송 메타 수신 (제목·브랜드 등)
      setTitle(info.title);
    case ShoplivePlaybackEvent(:final kind):                // 재생 종류: started / rendering / rebufferingStarted / rebufferingEnded / ended …
      if (kind == ShoplivePlaybackEventKind.rebufferingStarted) showSpinner(true);
      if (kind == ShoplivePlaybackEventKind.rebufferingEnded) showSpinner(false);
    case ShopliveConnectionStateChanged(:final state):      // 공통 연결 상태
      showNetworkBanner(state == ShopliveConnectionState.reconnecting);
    case ShopliveUserNameUpdateRequested(:final payload):   // 닉네임 변경 요청 → 앱 프로필 화면
      openProfileEditor(payload);
    case ShopliveAnalyticsEvent e:                          // 시청 통계 → 자체 분석으로 전달
      tracker.log(e.campaignKey, e.isPlaying, e.durationMs);
    case ShoplivePlayerErrorEvent(:final error):            // 복구 불가 오류만 전달
      show(error.message);
    case ShopliveWebCommandReceived(:final name, :final payload):   // 오버레이(웹)가 보낸 커스텀 명령 — 예: 로그인 요청
      handleWebCommand(name, payload);
    default:
      break;
  }
});

// 요청 — 종류마다 스트림 하나. 세션 내내 구독을 유지합니다
player.navigationRequests.listen((request) => router.open(request.url));
player.couponRequests.listen((request) {                    // 발급 후 결과 보고 (respond 는 1회만 유효 · 기본 10초 후 시간 초과)
  request.respond(const ShopliveCouponResult(success: true,
      status: ShopliveResultStatus.hide, alertType: ShopliveResultAlertType.toast));
});
player.customWebActionRequests.listen((request) {           // 동작 수행 후 결과 보고
  request.respond(const ShopliveCustomActionResult(success: true,
      status: ShopliveResultStatus.keep, alertType: ShopliveResultAlertType.toast));
});

player.send(command: "HIGHLIGHT_PRODUCT", payload: ["sku": "A-1024"])

player.send(command = "HIGHLIGHT_PRODUCT", payload = mapOf("sku" to "A-1024"))

await ShoplivePlayer.instance.send("HIGHLIGHT_PRODUCT", {"sku": "A-1024"});

var cfg = ShoplivePlayerConfiguration()
cfg.overlay.ui = .hidden        // 기본 오버레이 UI 감춤 (커맨드 채널은 유지)
let player = ShoplivePlayerViewController(campaignKey: key, configuration: cfg)
// 이제 채팅/상품/쿠폰 UI를 앱이 delegate 데이터로 직접 그립니다

val cfg = ShoplivePlayerConfiguration(
    overlay = ShoplivePlayerConfiguration.OverlayOptions(ui = ShopliveOverlayUIMode.HIDDEN)   // 표시만 숨김
)
ShoplivePlayer(context).start(campaignKey = key, configuration = cfg)
// 이제 채팅/상품/쿠폰 UI를 앱이 delegate 데이터로 직접 그립니다

await ShoplivePlayer.instance.start(key,
    configuration: const ShoplivePlayerConfiguration(
        overlay: ShopliveOverlayOptions(ui: ShopliveOverlayUIMode.hidden)));   // 표시만 숨김
// 이제 events·요청 스트림 데이터로 채팅·상품·쿠폰 UI 를 앱이 직접 그립니다

// 1) 송출 토큰 (필수)
Shoplive.setStreamToken(streamerJwt)

// 2) 스튜디오 실행
let studio = ShopliveStreamerViewController(campaignKey: "송출할_CAMPAIGN_KEY")
studio.streamerDelegate = self          // 선택
present(studio, animated: true)

// 3) 상태 수신 (선택)
extension MyViewController: ShopliveStreamerDelegate {
  func streamer(_ s: ShopliveStreamerViewController, didReceive event: ShopliveStreamerEvent) {
    switch event {
    case .stateChanged(let st): print("broadcast:", st)
    case .error(let e):         show(e.message)
    }
  }
}

// 1) 송출 토큰 (필수)
Shoplive.setStreamToken(streamerJwt)

// 2) 스튜디오 실행 — 런타임 권한도 SDK가 요청
ShopliveStreamer(context).apply {
    streamerDelegate = myStreamerDelegate   // 선택
}.start(campaignKey = "송출할_CAMPAIGN_KEY")

// 3) 상태 수신 (선택)
val myStreamerDelegate = object : ShopliveStreamerDelegate {
  override fun onEvent(s: ShopliveStreamer, event: ShopliveStreamerEvent) {
    when (event) {
      is ShopliveStreamerEvent.StateChanged -> log(event.state)
      is ShopliveStreamerEvent.Error -> show(event.error.message)
    }
  }
}

// 1) 송출 토큰 (필수)
await Shoplive.setStreamToken(streamerJwt);

final streamer = ShopliveStreamer.instance;
// 3) 상태 받기 (선택) — start 전에 구독
streamer.events.listen((event) {
  switch (event) {
    case ShopliveStreamerStateChanged(:final state):
      log(state);
    case ShopliveStreamerErrorEvent(:final error):
      show(error.message);
    default:
      break;
  }
});

// 2) 스튜디오 띄우기 — 런타임 권한 요청도 SDK 가 처리
await streamer.start("YOUR_CAMPAIGN_KEY");

struct ShopliveError: Error {
    let code: ShopliveErrorCode        // 타입화된 enum
    let message: String
    let rawCode: Int           // 원본 숫자 코드 (3.0.3+, code 가 unknown 이어도 보존)
    let underlying: Error?
    let isRecoverable: Bool    // 코드별 고정값 — true 면 SDK가 재시도·재접속으로 스스로 회복하는 종류
}

// 3.0.3부터 시청 · 송출 공통 — import cloud.shoplive.core.publicsurface.ShopliveError (· ShopliveErrorCode)
class ShopliveError(
    val code: ShopliveErrorCode,       // 타입화된 enum
    val rawCode: Int,                  // 서버·엔진이 준 원본 숫자 코드
    override val message: String?,
    override val cause: Throwable? = null,
    val isRecoverable: Boolean = code.isRecoverable,   // 코드별 고정값 — true 면 SDK가 재시도·재접속으로 스스로 회복하는 종류
) : Exception(message, cause)

// 오류 이벤트는 ShopliveError 를 싣습니다
class ShopliveError {
  final String code;          // SDK 3.0.3 의 오류 상수 이름 — 값이 늘 수 있으니 불투명한 문자열로 다룹니다
  final int? rawCode;         // 원본 숫자 코드 (3.0.3+ 두 플랫폼 모두 값)
  final String? message;
  final bool recoverable;     // true 면 SDK 가 스스로 복구 (재시도·재연결)
}

// 모든 API 는 Future 를 돌려주고, 실패하면 PlatformException 을 던집니다
// code: INVALID_ARGUMENT · NO_HOST_SCREEN · NOT_RUNNING · SDK_ERROR
try {
  await ShoplivePlayer.instance.start(campaignKey);
} on PlatformException catch (e) {
  if (e.code == ShoplivePlatformErrorCode.noHostScreen) { /* … */ }
}