Video commerce, in your iOS app.

Set up the host app first. Then create one player for one screen.

1. Add the binary package. Check its archive SHA-256 against the release record. Extract it. In Xcode, use File > Add Package Dependencies > Add Local. Select the extracted binary package folder. Add LiveMarketSDK to the app target.
2. Set the app target. Use iOS 18 or later, Swift 6, and Xcode 26 or later. Add WKAppBoundDomains to the app target's Info.plist.
3. Create the configuration. Supply the tenant client ID and content token through the host's approved secret path. Pick one environment and cart mode.
4. Install the cart callback. Set onAddToCart before load(_:).
5. Own the lifecycle. Keep the player on the main actor for the screen lifetime. Call destroy() when ownership ends.

The binary package contains an XCFramework and a small Package.swift. The separate integration archive contains Markdown guides and the host integration skill. This website contains the HTML guide.

The host app requires iPhone 12 or newer. Use the same approved archive and SHA-256 in each build configuration and CI run. Keep the extracted package path available to CI.

<key>WKAppBoundDomains</key>
<array/>

An empty array is valid for this player. Keep domains that other host WebViews need. Do not add a broad App Transport Security exception.

import LiveMarketSDK

let business = try LiveMarketBusiness(
    clientID: clientID,
    contentToken: contentToken
)
let config = LiveMarketSDKConfiguration(
    environment: .staging,
    business: business,
    cartMode: .message
)
let selection = try LiveMarketSelection(placementTag: placementTag)
let player = LiveMarketPlayer(configuration: config)

player.onAddToCart = { request in
    guard !Task.isCancelled else {
        return .rejected(message: "Cart request canceled.", retryAllowed: true)
    }
    // Apply request.requestID at most once in the host cart.
    return .rejected(message: "Connect the host cart.", retryAllowed: true)
}
player.load(selection, presentation: .single)

Use LiveMarketPlayerView(player:) in SwiftUI. Use LiveMarketPlayerUIView(player:) in UIKit. The view displays native controls and products around the video renderer.

LiveMarketPlayerView(player: player)
    .frame(height: player.height)

let playerView = LiveMarketPlayerUIView(player: player)
playerView.translatesAutoresizingMaskIntoConstraints = false
view.addSubview(playerView)
NSLayoutConstraint.activate([
    playerView.leadingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leadingAnchor),
    playerView.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor),
    playerView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
    playerView.heightAnchor.constraint(equalToConstant: player.height)
])

The host owns the app. Native SDK code owns content review, player state, cart handoff, and analytics. A locked WebView plays the selected video.

Load path

The SDK requests the selected placement with the content token. It checks the first page, its videos, resource URLs, and the requested presentation before it mounts the fixed local renderer. For a grid, it checks each later page before it adds those videos. The WebView does not receive the content or collector token. Native code accepts only validated bridge messages from the current player generation.

What is native?

Carousel, grid, feed selection, preview cards, product cards, playback controls, state, cart handoff, analytics, and diagnostics are native. The video element and its media events run inside the bundled WebView. The SDK keeps network origins and bridge commands fixed.

Create a new immutable configuration for each tenant and environment.

The SDK uses the app locale for its native control text. English and Polish are bundled. Other locales use English.

let style = LiveMarketPlayerStyle(
    accent: LiveMarketColor(red: 18, green: 96, blue: 180),
    text: LiveMarketColor(red: 20, green: 20, blue: 20),
    surface: LiveMarketColor(red: 255, green: 255, blue: 255),
    price: LiveMarketColor(red: 160, green: 24, blue: 40),
    typeDesign: .rounded
)
let business = try LiveMarketBusiness(
    clientID: clientID,
    contentToken: contentToken,
    collectorToken: collectorToken
)
let config = LiveMarketSDKConfiguration(
    environment: .staging,
    business: business,
    cartMode: .post,
    analytics: .enabled,
    productImageOrigins: ["https://images.example.com"],
    style: style
)
let selection = try LiveMarketSelection(
    placementTag: placementTag,
    contentLanguage: "pl"
)

Style affects SDK-owned native UI. It does not change the renderer or network policy. Use host-managed secret delivery. A mobile app user can inspect an app-owned token, so the service must limit its authority and support rotation.

A feed needs a carousel or grid placement with at least two videos. The requested presentation must match the service component. A new load replaces the old generation and cancels its work. A new video starts muted. Carousel and grid lists do not play until a video opens.

Fullscreen playback

Carousel and grid open fullscreen while the selected video loads. Swipe left for the next video. Swipe right for the previous video. The list does not wrap at either end. The same fullscreen surface stays open when the video changes.

At the end of the loaded grid videos, a forward swipe requests the next page. The current video stays open while the SDK reviews that page. The SDK opens the next video only after review succeeds. Swipe again after a failed page request to retry.

Swipe up or down, or use Close video, to close playback and return to the same list position. Playback and product controls keep their own gestures. Call closeActiveItem() to close the video from host code. Closing a carousel or grid video pauses playback.

Single video uses a manual fullscreen button. Exit returns the video to its inline view. Feed uses vertical swipes to change videos. The unused inline renderer space is transparent. The fullscreen background is black.

override func viewWillDisappear(_ animated: Bool) {
    super.viewWillDisappear(animated)
    if presentedViewController?.modalPresentationStyle != .overFullScreen {
        player.pause()
    }
}

override func viewDidDisappear(_ animated: Bool) {
    super.viewDidDisappear(animated)
    if isMovingFromParent || isBeingDismissed {
        player.destroy()
    }
}

If a custom container removes the controller, its owner must call destroy(). In SwiftUI, pause on a temporary disappearance if the host keeps the screen for later use. Destroy the player only when the screen lifetime ends.

Use itemCount for reviewed videos now loaded. Use totalItemCount for the reported total. The SDK accepts up to 500 videos in ten pages of 50. A grid requests the next page as the shopper nears the end of the loaded cards. It loads covers for visible cards and releases distant covers.

The SDK validates the selected product and variant. Your host app changes the cart.

LiveMarketCartRequest has generation, requestID, mode, contentID, optional viewID, productID, variantID, parameter, and quantity. Quantity is one in this version. Treat parameter as private data. Never open it as a URL.

player.onAddToCart = { request in
    guard !Task.isCancelled else {
        return .rejected(message: "Canceled.", retryAllowed: true)
    }
    do {
        // hostCart applies request.requestID at most once.
        try await hostCart.apply(request)
        return .accepted(message: "Item added to cart.")
    } catch {
        return .rejected(message: "Could not add item.", retryAllowed: true)
    }
}

Check cancellation again just before the cart mutation. Apply each requestID at most once. The SDK runs one request at a time and allows 15 seconds for a result. It cancels old work on replacement or destroy. An accepted cart result does not mean checkout or payment succeeded.

Analytics is off by default. The host app owns the consent decision.

1. Configure. Set analytics: .enabled and supply a collector token that differs from the content token.
2. Grant. Call grantAnalyticsConsent(userID:) only after the shopper agrees. Grant before load when possible.
3. Update. Call denyAnalyticsConsent() on withdrawal. Use reset, new session, or user ID methods when host identity changes.
4. Reload. Load the placement again after an identity change to start a new analytics view.

The SDK builds and sends its analytics events in native code. The WebView does not receive the collector token. Do not send a second copy of the SDK funnel from the host. The queue is memory only and bounded to 100 events. The host owns deletion requests for events already accepted by the collector.

LiveMarketAnalyticsIdentityManager(scope:) is available when the host needs one consent owner for the same tenant across players and windows. Use a stable tenant scope. Do not use a shopper ID as the scope. The player exposes matching consent methods for ordinary screen integration.

Call player and identity methods on the main actor. Set the cart callback before load.

Constructors and views

Player methods

Player values and callback

Identity manager methods

For failures, switch on LiveMarketPlaybackState.failed(error). Use error.code, error.message, and error.retryAllowed. The state also has .idle, .loading, .ready, .playing, .paused, .ended, and .destroyed. Use state.label for a short localized label.

The repository includes one host integration skill for an agent working in a customer iOS app.

1. Copy. Copy the full live-market-ios-integration skill folder from the integration archive into the customer app's .agents/skills/ directory.
2. Start in the host app. Run $live-market-ios-integration there. Read the host app's agent instructions first.
3. Give release inputs. Use the pinned SDK binary, archive SHA-256, release record, tenant, placement tags, cart mode, and consent choice. Do not paste raw tokens into chat.
4. Validate. Use the skill's feature map and validation matrix. Record pass, fail, or blocked for each applicable row.

The skill guides package setup, environment selection, every presentation, cart handoff, analytics consent, lifecycle, and release checks. It works in the host app. Its pinned release documentation and public Swift declarations control a customer integration.

Test fullscreen entry while the video loads. Test next and previous videos, grid page loading, page retry, and each close action. Check that closing playback keeps the list position. Check playback and product gestures. Keep the player alive while the SDK fullscreen view is open.

DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer \
  swift test --scratch-path /tmp/live-market-ios-sdk-tests

This command is for SDK maintainers with the source checkout. The macOS target does not exercise the iOS player. The media policy permits exact reviewed Mux hosts, including Google Cloud US East 1 hosts on edgemv.mux.com and fastly.mux.com. A customer app needs its own host tests and an approved release record. See the README for current behavior and release limits.