Callbacks

The Bambuser Commerce SDK provides the BambuserVideoPlayerDelegate interface for receiving events from the player. Implement it as an anonymous object passed to GetLiveView.

Interface Methods

• onNewEventReceived(playerId, event, viewAction) — Called when the player emits an event. Use viewAction to invoke player functions or respond with a notify.
• onErrorOccurred(playerId, error) — Called when an unrecoverable error occurs.
• onVideoStatusChanged(playerId, state, playerActions) — Called when playback state changes. Use playerActions to control playback programmatically.
• onVideoProgress(playerId, duration, currentTime) — Called periodically during playback with progress in seconds.

ℹ️ onVideoStatusChanged and onVideoProgress have default empty implementations — they are optional to override.

Example Implementation

val videoPlayerDelegate = object : BambuserVideoPlayerDelegate {

    override fun onNewEventReceived(
        playerId: String,
        event: BambuserEventPayload,
        viewAction: ViewActions
    ) {
        when (event.event) {   // event.event is the event type string
            "provide-product-data" -> {
                // Hydrate products — see Product Hydration
            }
            "should-add-item-to-cart" -> {
                val callbackKey = event.callbackKey ?: return  // callbackKey is top-level
                val sku = event.data["sku"] as? String ?: return
                // Add to cart, then respond:
                lifecycleScope.launch {
                    viewAction.notifyView(callbackKey, true)
                }
            }
        }
    }

    override fun onErrorOccurred(playerId: String, error: Exception) {
        Log.e("BambuserPlayer", "Error in player $playerId: ${error.message}")
    }

    override fun onVideoStatusChanged(
        playerId: String,
        state: BambuserVideoState,
        playerActions: PlayerActions
    ) {
        Log.d("BambuserPlayer", "Player $playerId state: $state")
        // Use playerActions to control playback if needed:
        // playerActions.play() / playerActions.pause() / playerActions.mute() / playerActions.unMute()
    }

    override fun onVideoProgress(playerId: String, duration: Long, currentTime: Long) {
        Log.d("BambuserPlayer", "Progress: $currentTime / $duration seconds")
    }
}

Player States

BambuserVideoState values reported via onVideoStatusChanged:

State	When it fires
INITIALIZED	Player object created
CONSTRUCTION	Player is being constructed
LOADING	Player is initialising or fetching the stream
BUFFERING	Stream is buffering
READY	Player is ready but not yet playing
PLAYING	Playback is active
PAUSED	Playback was paused
COMPLETED	Playback finished (video-on-demand)
ERROR	An unrecoverable error occurred
CLOSED	Player was closed

Live player state sequence with autoplay: true: LOADING → PLAYING

PlayerActions Interface

PlayerActions is provided in the onVideoStatusChanged callback and gives you programmatic control over the player:

override fun onVideoStatusChanged(
    playerId: String,
    state: BambuserVideoState,
    playerActions: PlayerActions
) {
    if (state == BambuserVideoState.READY) {
        playerActions.play()  // start playback manually when autoplay is false
    }
}

Method	Description
play()	Starts or resumes playback
pause()	Pauses playback
mute()	Mutes audio
unMute()	Unmutes audio

ViewActions Interface

ViewActions is provided in the onNewEventReceived callback and lets you communicate with the player WebView:

override fun onNewEventReceived(
    playerId: String,
    event: BambuserEventPayload,
    viewAction: ViewActions
) {
    // Invoke a player function (suspend — must run in a coroutine)
    lifecycleScope.launch {
        viewAction.invoke(function = "updateProductWithData", arguments = hydrationString)
    }

    // Respond to a player event that has a callbackKey
    val callbackKey = event.callbackKey ?: return
    viewAction.notifyView(callbackKey, true)   // or a JSON string for complex responses
}

Method	When to use
invoke()	Push data TO the player (async/suspend) — product hydration, wishlist sync
notifyView()	Respond to events that have a callbackKey — cart, wishlist actions

⚠️ Do not use viewAction.invoke(), viewAction.notifyView(), or viewAction.switchScreenMode() while the player is in PiP mode.

Event Payload Structure

BambuserEventPayload fields:

Field	Type	Description
event	String	The event type string (e.g. "should-add-item-to-cart")
data	Map<String, Any>	The event data dictionary (product info, SKU, quantity, etc.)
callbackKey	String?	Present when the player expects a notifyView response

ℹ️ On Android, callbackKey is a top-level field (event.callbackKey), not inside event.data. This differs from the iOS SDK where it is accessed as event.data["callbackKey"].