Cart integration

Cart integration synchronizes the Bambuser player's in-player cart with your native app cart. The player emits events when users interact with products, and your app responds using the notify method on BambuserPlayerView.

Handle Add to Cart

When a user taps Add to Cart in the player, a should-add-item-to-cart event is emitted. Extract the SKU and quantity, update your cart, then call notify with the result.

func onNewEventReceived(id: String, event: BambuserEventPayload) {
    switch event.type {

    case "should-add-item-to-cart":
        guard let callbackKey = event.data["callbackKey"] as? String,
              let productData = event.data["event"] as? [String: Sendable],
              let sku = productData["sku"] as? String,
              let quantity = productData["quantity"] as? Int else { return }

        Task {
            let success = await YourCartService.addItem(sku: sku, quantity: quantity)
            if success {
                self.playerView?.notify(callbackKey: callbackKey, info: true)
            } else {
                // Respond with failure if the item is out of stock
                self.playerView?.notify(
                    callbackKey: callbackKey,
                    info: "{ success: false, reason: 'out-of-stock' }"
                )
            }
        }

    default:
        break
    }
}

Handle Update Cart

When a user changes the quantity of an item already in the player's cart, a should-update-item-in-cart event is emitted.

case "should-update-item-in-cart":
    guard let callbackKey = event.data["callbackKey"] as? String,
          let productData = event.data["event"] as? [String: Sendable],
          let sku = productData["sku"] as? String,
          let quantity = productData["quantity"] as? Int else { return }

    Task {
        await YourCartService.updateItem(sku: sku, quantity: quantity)
        self.playerView?.notify(callbackKey: callbackKey, info: true)
    }

Sync Cart State

When the viewer navigates back to the player, it requests the current cart state via should-sync-cart-state. Respond with the current list of cart items so the player can reflect the correct quantities.

case "should-sync-cart-state":
    guard let callbackKey = event.data["callbackKey"] as? String else { return }

    // Build a list of current cart items: [{ sku: String, quantity: Int }]
    let cartItems = YourCartService.currentItems().map { ["sku": $0.sku, "quantity": $0.quantity] }
    if let jsonData = try? JSONSerialization.data(withJSONObject: cartItems),
       let jsonString = String(data: jsonData, encoding: .utf8) {
        self.playerView?.notify(callbackKey: callbackKey, info: jsonString)
    }

Notify Response Reference

    let cartItems = YourCartService.currentItems().map { ["sku": $0.sku, "quantity": $0.quantity] }
    if let jsonData = try? JSONSerialization.data(withJSONObject: cartItems),
       let jsonString = String(data: jsonData, encoding: .utf8) {
        self.playerView?.notify(callbackKey: callbackKey, info: jsonString)
    }

Here are example responses when calling notify:

Scenario	info value	Example
Success	true	swift self.playerView?.notify(callbackKey: callbackKey, info: true)
Out of stock	"{ success: false, reason: 'out-of-stock' }"	swift self.playerView?.notify( callbackKey: callbackKey, info: "{ success: false, reason: 'out-of-stock' }" )
Custom failure	"{ success: false, reason: 'your-reason' }"	swift self.playerView?.notify( callbackKey: callbackKey, info: "{ success: false, reason: 'your-reason' }" )

Conversion Tracking

After a purchase completes in your app, report it to Bambuser Analytics using the track function. This attributes conversions to the live show.

let response = try? await self.playerView?.track(
    event: "purchase",
    with: [
        "transaction": [
            "id": "ORDER-12345",
            "subtotal": 70.99,
            "currency": "USD",
            "total": 74.98,
            "tax": 4.0,
            "shippingCost": 3.99,
            "shippingMethod": "Standard",
            "coupon": "SUMMER_SALE"
        ],
        "products": [
            [
                "id": "314-7216-102",
                "name": "Tennis Shoe Classic - Size 10",
                "image": "https://example.com/images/314-7216-102.jpg",
                "price": 70.99,
                "currency": "USD",
                "quantity": 1,
                "brand": "Example Brand",
                "category": "Footwear > Sports > Tennis",
                "location": "https://example.com/products/314-7216"
            ]
        ]
    ]
)

For the full event data schema, refer to the Bambuser iOS SDK on GitHub.