Cart integration

Cart integration connects the Bambuser player's add-to-cart and checkout UI to your app's native cart. Handle the three cart events in your BambuserVideoPlayerDelegate and respond using viewAction.notifyView().

Cart Events

Event	callbackKey	Response
should-add-item-to-cart	Yes	notifyView(callbackKey, true) or out-of-stock error
should-update-item-in-cart	Yes	notifyView(callbackKey, true) or out-of-stock error
should-sync-cart-state	Yes	notifyView(callbackKey, cartItemsJson)

1. Add Item to Cart

Fires when the user taps Buy on a product that is not yet in the cart.

override fun onNewEventReceived(
    playerId: String,
    event: BambuserEventPayload,
    viewAction: ViewActions
) {
    when (event.event) {

        "should-add-item-to-cart" -> {
            val callbackKey = event.callbackKey ?: return
            val sku      = event.data["sku"] as? String ?: return
            val quantity = (event.data["quantity"] as? Number)?.toInt() ?: 1

            lifecycleScope.launch {
                val success = YourCartService.addItem(sku = sku, quantity = quantity)
                if (success) {
                    viewAction.notifyView(callbackKey, true)
                } else {
                    viewAction.notifyView(callbackKey, "{ success: false, reason: 'out-of-stock' }")
                }
            }
        }
    }
}

2. Update Item in Cart

Fires when the user taps Buy on a product already in the cart, or changes quantity from the cart page.

"should-update-item-in-cart" -> {
    val callbackKey = event.callbackKey ?: return
    val sku      = event.data["sku"] as? String ?: return
    val quantity = (event.data["quantity"] as? Number)?.toInt() ?: 1

    lifecycleScope.launch {
        val success = YourCartService.updateItem(sku = sku, quantity = quantity)
        if (success) {
            viewAction.notifyView(callbackKey, true)
        } else {
            viewAction.notifyView(callbackKey, "{ success: false, reason: 'out-of-stock' }")
        }
    }
}

3. Sync Cart State

Fires when the player needs to refresh its cart state, for example when navigating back to the player from checkout. Respond with the current cart as a JSON array.

"should-sync-cart-state" -> {
    val callbackKey = event.callbackKey ?: return
    val items = YourCartService.currentItems().map {
        mapOf("sku" to it.sku, "quantity" to it.quantity)
    }
    val json = Gson().toJson(items)
    viewAction.notifyView(callbackKey, json)
}

notifyView Response Reference

Scenario	Info value
Success	true
Out of stock	"{ success: false, reason: 'out-of-stock' }"
Custom failure	"{ success: false, reason: 'your-reason' }"
Cart state	JSON array: "[{\"sku\":\"abc\",\"quantity\":1}]"

Complete Cart Handler

val videoPlayerDelegate = object : BambuserVideoPlayerDelegate {
    override fun onNewEventReceived(
        playerId: String,
        event: BambuserEventPayload,
        viewAction: ViewActions
    ) {
        when (event.event) {

            "should-add-item-to-cart" -> {
                val callbackKey = event.callbackKey ?: return
                val sku      = event.data["sku"] as? String ?: return
                val quantity = (event.data["quantity"] as? Number)?.toInt() ?: 1

                lifecycleScope.launch {
                    val success = YourCartService.addItem(sku, quantity)
                    viewAction.notifyView(
                        callbackKey,
                        if (success) true else "{ success: false, reason: 'out-of-stock' }"
                    )
                }
            }

            "should-update-item-in-cart" -> {
                val callbackKey = event.callbackKey ?: return
                val sku      = event.data["sku"] as? String ?: return
                val quantity = (event.data["quantity"] as? Number)?.toInt() ?: 1

                lifecycleScope.launch {
                    YourCartService.updateItem(sku, quantity)
                    viewAction.notifyView(callbackKey, true)
                }
            }

            "should-sync-cart-state" -> {
                val callbackKey = event.callbackKey ?: return
                val items = YourCartService.currentItems().map {
                    mapOf("sku" to it.sku, "quantity" to it.quantity)
                }
                viewAction.notifyView(callbackKey, Gson().toJson(items))
            }
        }
    }

    override fun onErrorOccurred(playerId: String, error: Exception) { }
}

Conversion Tracking

Call track() on your SDK instance after a purchase completes in your app. This is a suspend function and must run inside a coroutine:

lifecycleScope.launch {
    globalBambuserSDK.track(
        eventName = "purchase",
        data = mapOf(
            "purchase" to mapOf(
                "id"             to "ORDER-123",
                "subtotal"       to 70.99,
                "currency"       to "USD",
                "total"          to 74.98,
                "tax"            to 4.0,
                "shippingCost"   to 3.99,
                "shippingMethod" to "Standard",
                "coupon"         to "SUMMER_SALE",
            ),
            "products" to listOf(
                mapOf(
                    "id"       to "sku-123",
                    "name"     to "Tennis Shoe Classic - Size 10",
                    "image"    to "https://example.com/images/shoe.jpg",
                    "price"    to 70.99,
                    "currency" to "USD",
                    "quantity" to 1,
                    "brand"    to "Plausible Co.",
                    "category" to "Footwear > Sports > Tennis",
                )
            )
        )
    )
}

track() is a method on BambuserSDK (not on viewAction). Call it from any coroutine scope with access to your SDK instance.