Shoplive SDK Integration Guide

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

// Add only the libraries your target needs, and import only what you use.
import ShoplivePlayerSDK     // viewing — missions 1-7
import ShopliveStreamerSDK   // broadcasting — mission 8 (only if you ship it)

// ShopliveCore (auth · config · user) comes along with the SDKs above.
// You call Shoplive.initialize and setUser without importing it.

// settings.gradle.kts — add the Shoplive Maven repository
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")     // viewing
    implementation("cloud.shoplive:shoplive-streamer-sdk:3.0.3")   // broadcasting
    // core is pulled in automatically by the SDKs above
}

# pubspec.yaml — Flutter 3.22 or later · Dart 3.4 or later
dependencies:
  shoplive_player: 3.0.3     # viewing (includes shoplive_core)
  shoplive_streamer: 3.0.3   # broadcasting — only if you need it

# ios/Podfile — the iOS SDK needs iOS 15 (the frameworks download during pod install)
platform :ios, "15.0"
# Android: the plugins add the Shoplive Maven repository for you

// 1) Once at app startup
Shoplive.initialize(.init(accessKey: "YOUR_ACCESS_KEY"))
// 2) Identify the user — signed-in users only (skip for guests, Mission 3)
Shoplive.setUser(.token(jwt: myJwt))
// 3) Play
let player = ShoplivePlayerViewController(campaignKey: "YOUR_CAMPAIGN_KEY")
present(player, animated: true)

// 1) Once at app startup
Shoplive.initialize(context, ShopliveConfiguration("YOUR_ACCESS_KEY"))
// 2) Identify the user — signed-in users only (skip for guests, Mission 3)
Shoplive.setUser(ShopliveUser.Token(myJwt))
// 3) Play (starts as soon as the instance is created)
ShoplivePlayer(context).start(campaignKey = "YOUR_CAMPAIGN_KEY")

import "package:shoplive_player/shoplive_player.dart";

// 1) Once at app startup
await Shoplive.initialize(const ShopliveConfiguration(accessKey: "YOUR_ACCESS_KEY"));
// 2) Identify the user — signed-in users only (skip for guests, Mission 3)
await Shoplive.setUser(ShopliveUser.token(myJwt));
// 3) Play
await ShoplivePlayer.instance.start("YOUR_CAMPAIGN_KEY");

Shoplive.initialize(.init(accessKey: "YOUR_ACCESS_KEY"))
Shoplive.setStreamToken(streamerJwt)          // broadcast-only token (required)

let studio = ShopliveStreamerViewController(campaignKey: "YOUR_CAMPAIGN_KEY")
present(studio, animated: true)

Shoplive.initialize(context, ShopliveConfiguration("YOUR_ACCESS_KEY"))
Shoplive.setStreamToken(streamerJwt)          // broadcast-only token (required)

ShopliveStreamer(context).start(campaignKey = "YOUR_CAMPAIGN_KEY")

import "package:shoplive_streamer/shoplive_streamer.dart";

await Shoplive.initialize(const ShopliveConfiguration(accessKey: "YOUR_ACCESS_KEY"));
await Shoplive.setStreamToken(streamerJwt);   // broadcast-only token (required)

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

@IBAction func watchLive() {
    let player = ShoplivePlayerViewController(campaignKey: "YOUR_CAMPAIGN_KEY")
    player.delegate = self               // optional: receive events
    present(player, animated: true)
}

fun watchLive() {
    ShoplivePlayer(context).apply {
        delegate = myDelegate            // optional: receive events
    }.start(campaignKey = "YOUR_CAMPAIGN_KEY")
}

Future<void> watchLive() async {
  final player = ShoplivePlayer.instance;
  player.events.listen(onPlayerEvent);   // optional: receive events (Mission 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 that receives the deep link
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))
}

// Call with the deep link URI your app receives (for example from app_links or 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));
}

// ① Signed in · secure auth (recommended) — a JWT signed by your backend (Step 4)
Shoplive.setUser(.token(jwt: myJwt))

// ② Signed in · simple auth — pass the profile directly (the SDK builds an unsigned JWT)
Shoplive.setUser(.profile(
    id: hashedUserId,            // a hash is recommended over the raw ID (Step 3)
    name: "LiveFan", age: 27, gender: .female,
    rank: 10))                    // user grade (-100 to 100)

// ③ Signed out — no call needed

// Log out — clears the user info (JWT, profile) and also the broadcasting token (accessKey, guest identifier and UTM stay)
Shoplive.logout()

// ① Signed in · secure auth (recommended) — a JWT signed by your backend (Step 4)
Shoplive.setUser(ShopliveUser.Token(myJwt))

// ② Signed in · simple auth — pass the profile directly (the SDK builds an unsigned JWT)
Shoplive.setUser(ShopliveUser.Profile(
    id = hashedUserId,           // a hash is recommended over the raw ID (Step 3)
    name = "LiveFan", age = 27, gender = ShopliveGender.FEMALE,
    rank = 10))                    // user grade (-100 to 100)

// ③ Signed out — no call needed

// Log out — clears the user info (JWT, profile) and also the broadcasting token (accessKey, guest identifier and UTM stay)
Shoplive.logout()

// ① Signed in · secure auth (recommended) — a JWT signed by your backend (Step 4)
await Shoplive.setUser(ShopliveUser.token(myJwt));

// ② Signed in · simple auth — pass the profile directly (the SDK builds an unsigned JWT)
await Shoplive.setUser(ShopliveUser.profile(
    id: hashedUserId,            // a hash is recommended over the raw ID (Step 3)
    name: "LiveFan", age: 27, gender: ShopliveGender.female,
    rank: 10));                    // user grade (-100 to 100)

// ③ Signed out — no call needed

// Sign-out — clears user info and tokens
await Shoplive.logout();

// Preview preset — low resolution (type = .preview), mute, hidden overlay and in-App PIP policy in one go
let playerView = ShoplivePlayerView(configuration: .preview)
container.addSubview(playerView)       // Auto Layout is up to the host app
playerView.delegate = self
playerView.play(campaignKey: "YOUR_CAMPAIGN_KEY")

val playerView = ShoplivePlayerView(context)   // free to place in XML/Compose (AndroidView)
// Preview preset — low resolution (PREVIEW), mute, hidden overlay and in-App PIP policy in one go
playerView.configuration = ShoplivePlayerConfiguration.PREVIEW
container.addView(playerView)

playerView.delegate = myDelegate
playerView.bindLifecycle(viewLifecycleOwner)   // automates pause/resume/release
playerView.play(campaignKey = "YOUR_CAMPAIGN_KEY")

// Flutter 3.0.3 still has no widget to embed in a feed (no ShoplivePlayerView).
// Closest option: start the preview stream as a small in-app PIP window
await ShoplivePlayer.instance.start("YOUR_CAMPAIGN_KEY",
    playOptions: const ShoplivePlayOptions(presentationStyle: ShoplivePresentationStyle.pip),
    configuration: const ShoplivePlayerConfiguration(
        type: ShoplivePlayerType.preview,                            // preview stream (low resolution)
        sound: ShopliveSoundOptions(muteOnStart: true),              // start muted
        overlay: ShopliveOverlayOptions(ui: ShopliveOverlayUIMode.hidden),   // hide overlays
        pip: ShoplivePipOptions(isInAppPipEnabled: true)));          // required for presentationStyle: pip

playerView.stop()                      // stop the preview
let player = ShoplivePlayerViewController(campaignKey: "YOUR_CAMPAIGN_KEY")   // opens at full resolution
present(player, animated: true)

playerView.stop()                      // stop the preview
ShoplivePlayer(context).start(campaignKey = "YOUR_CAMPAIGN_KEY")   // default type = LIVE

// Switch to full playback at full resolution — on iOS a running session switches in place
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")   // register before creating the WKWebView (with this 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)   // Step 3 · play natively
}

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

class ShopLiveAppInterface(private val activity: Activity) {
    @JavascriptInterface                     // called on a background thread
    fun postMessage(campaignKey: String) {
        activity.runOnUiThread { playLive(activity, campaignKey) }   // Step 3 · play natively
    }
}

// webview_flutter — exposes window.ShopLiveAppInterface.postMessage to the page
controller.addJavaScriptChannel(
  "ShopLiveAppInterface",
  onMessageReceived: (JavaScriptMessage message) {
    playLive(message.message);   // Step 3 · play natively
  },
);

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);

// Signed in — right before playback (Mission 3)
Shoplive.setUser(.token(jwt: jwt))
// then play as in Step 3

// Signed in — right before playback (Mission 3)
Shoplive.setUser(ShopliveUser.Token(jwt))
// then play as in Step 3

// Signed in — right before playback (Mission 3)
await Shoplive.setUser(ShopliveUser.token(jwt));
// then play as in Step 3

player.enterPictureInPicture()      // shrink to a small window
player.exitPictureInPicture()       // back to normal
if player.isInPictureInPicture { /* … */ }

// Position, scale, and so on come from configuration
var cfg = ShoplivePlayerConfiguration()
cfg.pip.defaultPosition = .bottomRight
cfg.pip.scale = 0.4
cfg.pip.isOSPipEnabled = true

player.enterPictureInPicture()      // shrink to a small window
player.exitPictureInPicture()       // back to normal
if (player.isInPictureInPicture) { /* … */ }

// Position, scale, and so on come from configuration
val cfg = ShoplivePlayerConfiguration(
    pip = ShoplivePlayerConfiguration.PipOptions(
        defaultPosition = ShoplivePipPosition.BOTTOM_RIGHT,
        scale = 0.4f,
        isOSPipEnabled = true))     // OS PIP is available only with the Activity approach

final player = ShoplivePlayer.instance;
await player.enterPictureInPicture();   // shrink to a small window
await player.exitPictureInPicture();    // back to normal
if (await player.isInPictureInPicture()) { /* … */ }

// Position, scale, and so on come from configuration (merged on top of the current settings)
await player.setConfiguration(const ShoplivePlayerConfiguration(
    pip: ShoplivePipOptions(
        defaultPosition: ShoplivePipPosition.bottomRight,
        scale: 0.4,
        isOSPipEnabled: true)));   // Android: also add android:supportsPictureInPicture="true" to the host Activity

var options = ShoplivePlayOptions()
options.presentationStyle = .pip            // default is .fullScreen

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

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

await ShoplivePlayer.instance.start(key,
    playOptions: const ShoplivePlayOptions(
        presentationStyle: ShoplivePresentationStyle.pip));   // default is fullscreen — fails with INVALID_ARGUMENT if pip.isInAppPipEnabled is off

player.configuration = .preview                     // muted · overlay hidden · in-App PIP
player.play(campaignKey: key, options: .preview)    // presentationStyle = .pip

// Start from the preset and adjust (value type, so it copies)
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),             // muted
        overlay = ShoplivePlayerConfiguration.OverlayOptions(ui = ShopliveOverlayUIMode.HIDDEN)))  // overlay hidden

// Flutter has no presets — set the same values directly
await ShoplivePlayer.instance.start(key,
    playOptions: const ShoplivePlayOptions(presentationStyle: ShoplivePresentationStyle.pip),
    configuration: const ShoplivePlayerConfiguration(
        sound: ShopliveSoundOptions(muteOnStart: true),                       // muted
        overlay: ShopliveOverlayOptions(ui: ShopliveOverlayUIMode.hidden)));   // overlay hidden

extension MyViewController: ShoplivePlayerDelegate {

  // Notifications — all cases. Feel free to keep only the cases you need
  func player(_ p: ShoplivePlayerControlling, didReceive event: ShoplivePlayerEvent) {
    switch event {
    case .stateChanged(let s):              // playback lifecycle (includes entering/leaving .inAppPIP)
        print("state:", s)
    case .campaignStatusChanged(let c):     // .ready / .live / .ended
        liveBadge.isHidden = (c != .live)
    case .campaignInfoReceived(let info):   // campaign metadata received (title, brand, etc.)
        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):   // common connection state
        networkBanner.isHidden = (cs != .reconnecting)
    case .userNameUpdateRequested(let payload):  // nickname change requested → app profile screen
        openProfileEditor(payload)
    case .analytics(let info):              // viewing statistics → forward to your own analytics
        tracker.log(info.campaignKey, info.isPlaying, info.durationMs)
    case .error(let e):                     // only unrecoverable errors are delivered
        show(e.message)
    case .webCommand(let name, let payload):  // custom command sent by the overlay (web) — e.g. a login request
        handleWebCommand(name, payload)
    }
  }

  func player(_ p: ShoplivePlayerControlling, didRequest request: ShoplivePlayerRequest) {
    switch request {
    case .navigation(let url):  router.open(url)      // product/banner landing
    case .coupon(let id, let respond):            // report the result after issuing — status: popup handling (.show/.hide/.keep), alertType: .alert/.toast
        respond(ShopliveCouponResult(couponId: id, success: true, status: .hide, alertType: .toast))
    case .customWebAction(let id, _, _, let respond):  // report the result after performing the action
        respond(ShopliveCustomActionResult(id: id, success: true, status: .keep, alertType: .toast))
    }
  }
}

val myDelegate = object : ShoplivePlayerDelegate {

  // Notifications — all cases. Feel free to keep only the cases you need (default implementations are empty)
  override fun onEvent(p: ShoplivePlayerControlling, event: ShoplivePlayerEvent) {
    when (event) {
      is ShoplivePlayerEvent.StateChanged ->             // playback lifecycle (includes entering/leaving IN_APP_PIP)
          log(event.state)
      is ShoplivePlayerEvent.CampaignStatusChanged ->    // READY / LIVE / ENDED
          liveBadge.isVisible = event.status == ShopliveCampaignStatus.LIVE
      is ShoplivePlayerEvent.CampaignInfoReceived ->     // campaign metadata received (title, brand, etc.)
          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 ->   // common connection state
          networkBanner.isVisible = event.state == ShopliveConnectionState.RECONNECTING
      is ShoplivePlayerEvent.UserNameUpdateRequested ->  // nickname change requested → app profile screen
          openProfileEditor(event.payload)
      is ShoplivePlayerEvent.Analytics ->                // viewing statistics → forward to your own analytics
          tracker.log(event.info.campaignKey, event.info.isPlaying, event.info.durationMs)
      is ShoplivePlayerEvent.Error ->                    // only unrecoverable errors are delivered
          show(event.error.message)
      is ShoplivePlayerEvent.WebCommandReceived ->      // custom command sent by the overlay (web) — e.g. a login request
          handleWebCommand(event.name, event.payload)
    }
  }

  override fun onRequest(p: ShoplivePlayerControlling, request: ShoplivePlayerRequest) {
    when (request) {
      is ShoplivePlayerRequest.Navigation -> router.open(request.url)
      is ShoplivePlayerRequest.Coupon ->             // report the result after issuing — status: popup handling (SHOW/HIDE/KEEP), alertType: ALERT/TOAST
          request.respond(ShopliveCouponResult(couponId = request.id, success = true,
              status = ShopliveResultStatus.HIDE, alertType = ShopliveResultAlertType.TOAST))
      is ShoplivePlayerRequest.CustomWebAction ->    // report the result after performing the action
          request.respond(ShopliveCustomActionResult(id = request.id, success = true,
              status = ShopliveResultStatus.KEEP, alertType = ShopliveResultAlertType.TOAST))
    }
  }
}

final player = ShoplivePlayer.instance;

// Notifications — the events stream. Keep only the cases you need
player.events.listen((event) {
  switch (event) {
    case ShoplivePlayerStateChanged(:final state):          // playback lifecycle (includes inAppPip)
      log(state);
    case ShopliveCampaignStatusChanged(:final status):      // ready / live / ended
      showLiveBadge(status == ShopliveCampaignStatus.live);
    case ShopliveCampaignInfoReceived(:final info):         // campaign metadata received (title, brand, etc.)
      setTitle(info.title);
    case ShoplivePlaybackEvent(:final kind):                // playback kind: started / rendering / rebufferingStarted / rebufferingEnded / ended …
      if (kind == ShoplivePlaybackEventKind.rebufferingStarted) showSpinner(true);
      if (kind == ShoplivePlaybackEventKind.rebufferingEnded) showSpinner(false);
    case ShopliveConnectionStateChanged(:final state):      // common connection state
      showNetworkBanner(state == ShopliveConnectionState.reconnecting);
    case ShopliveUserNameUpdateRequested(:final payload):   // nickname change requested → app profile screen
      openProfileEditor(payload);
    case ShopliveAnalyticsEvent e:                          // viewing statistics → forward to your own analytics
      tracker.log(e.campaignKey, e.isPlaying, e.durationMs);
    case ShoplivePlayerErrorEvent(:final error):            // only unrecoverable errors are delivered
      show(error.message);
    case ShopliveWebCommandReceived(:final name, :final payload):   // custom command sent by the overlay (web) — e.g. a login request
      handleWebCommand(name, payload);
    default:
      break;
  }
});

// Requests — one stream per kind. Keep the listeners for the whole session
player.navigationRequests.listen((request) => router.open(request.url));
player.couponRequests.listen((request) {                    // report the result after issuing (respond is valid once; times out after 10 s by default)
  request.respond(const ShopliveCouponResult(success: true,
      status: ShopliveResultStatus.hide, alertType: ShopliveResultAlertType.toast));
});
player.customWebActionRequests.listen((request) {           // report the result after performing the action
  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        // hide the default overlay UI (the command channel stays alive)
let player = ShoplivePlayerViewController(campaignKey: key, configuration: cfg)
// Now your app draws the chat/product/coupon UI itself from the delegate data

val cfg = ShoplivePlayerConfiguration(
    overlay = ShoplivePlayerConfiguration.OverlayOptions(ui = ShopliveOverlayUIMode.HIDDEN)   // hides display only
)
ShoplivePlayer(context).start(campaignKey = key, configuration = cfg)
// Now your app draws the chat/product/coupon UI itself from the delegate data

await ShoplivePlayer.instance.start(key,
    configuration: const ShoplivePlayerConfiguration(
        overlay: ShopliveOverlayOptions(ui: ShopliveOverlayUIMode.hidden)));   // hides display only
// Now your app draws the chat/product/coupon UI itself from the events and requests streams

// 1) Broadcasting token (required)
Shoplive.setStreamToken(streamerJwt)

// 2) Launch the studio
let studio = ShopliveStreamerViewController(campaignKey: "YOUR_CAMPAIGN_KEY")
studio.streamerDelegate = self          // optional
present(studio, animated: true)

// 3) Receive state (optional)
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) Broadcasting token (required)
Shoplive.setStreamToken(streamerJwt)

// 2) Launch the studio — the SDK also requests runtime permissions
ShopliveStreamer(context).apply {
    streamerDelegate = myStreamerDelegate   // optional
}.start(campaignKey = "YOUR_CAMPAIGN_KEY")

// 3) Receive state (optional)
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) Broadcasting token (required)
await Shoplive.setStreamToken(streamerJwt);

final streamer = ShopliveStreamer.instance;
// 3) Receive state (optional) — subscribe before start
streamer.events.listen((event) {
  switch (event) {
    case ShopliveStreamerStateChanged(:final state):
      log(state);
    case ShopliveStreamerErrorEvent(:final error):
      show(error.message);
    default:
      break;
  }
});

// 2) Launch the studio — the SDK also requests runtime permissions
await streamer.start("YOUR_CAMPAIGN_KEY");

struct ShopliveError: Error {
    let code: ShopliveErrorCode        // a typed enum
    let message: String
    let rawCode: Int           // original numeric code (3.0.3+, kept even when code is unknown)
    let underlying: Error?
    let isRecoverable: Bool    // fixed per code — true means a kind the SDK recovers from by itself (retry/reconnect)
}

// Shared by viewing and broadcasting from 3.0.3 — import cloud.shoplive.core.publicsurface.ShopliveError (· ShopliveErrorCode)
class ShopliveError(
    val code: ShopliveErrorCode,       // a typed enum
    val rawCode: Int,                  // raw numeric code from the server/engine
    override val message: String?,
    override val cause: Throwable? = null,
    val isRecoverable: Boolean = code.isRecoverable,   // fixed per code — true means a kind the SDK recovers from by itself (retry/reconnect)
) : Exception(message, cause)

// Error events carry a ShopliveError
class ShopliveError {
  final String code;          // SDK 3.0.3 error constant name — new values can appear, so treat it as an opaque string
  final int? rawCode;         // raw numeric code (3.0.3+, set on both platforms)
  final String? message;
  final bool recoverable;     // true means the SDK recovers by itself (retry/reconnect)
}

// Every API call returns a Future and fails with 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) { /* … */ }
}