Bambuser Social Commerce SDK Android

Overview

BambuserCommerceSDK is a lightweight SDK for integrating Bambuser video player and commerce experience into your android applications in order to enhance your app with interactive video commerce features that streamline the video shopping experience.

Requirements

Targets Android 35
Minimal support API is 26 (Android 8+)
Compose BOM version is 2025.02.00
Kotlin version => 2.0.0

Installation

First, add a new maven repository to your dependency resolution management:

repositories {
  google()
  mavenCentral()
  // other repositories you might have...
  
  maven {
      url "https://repo.repsy.io/mvn/bambuser/bambuser-commerce-sdk"
  }
}

Then add the dependency into your app/build.gradle:

implementation("com.bambuser:commerce-sdk:$insert the latest version")

Player Initialization

The SDK provides flexible setup options so you can configure the player dynamically based on your needs, supporting live, pre-recorded, and shoppable video.

Quick Start

For complete examples and working integrations, check out our example app.

Setup

Loading Shoppable Video via SDK is very simple; you can request the videos available in Bamhub.

Create Video Configuration

You need to create the configururation for each shoppable videos. The general configuration setup looks like below. For more details on video configurations please check our Preview API Reference and Player API Reference page.

Shoppable Video Config
val shoppableVideoConfigurations = mapOf(
    "thumbnail" to mapOf(
        "enabled" to true, // IF false, it will show a black screen
        "showPlayButton" to true,
        "showLoadingIndicator" to true,
        //preview" to "", Add a custom thumbnail image URL if needed
    ),
    // Configuration for preview mode
    "previewConfig" to mapOf(
        "settings" to "products:true; title: false; actions:1; productCardMode: thumbnail",
    ),
    // Configuration for fullscreen mode
    "playerConfig" to mapOf(
        "buttons" to mapOf(
            "dismiss" to "event",
            "product" to "event",
        ),
        "currency" to "USD", // Mandatory for product hydration
    )
)

Now you can use this configuration to load videos in three different ways

Create a playlist in the BamHub and fetch it by using the Page concept
Construct a playlists via the SKU. Fetch the videos where the product SKU is added
Embed individual videos via the Video IDs. If you already have a Bambuser video ID.

Get Playlist videos

// Initialize the Bambuser video player with the server region
// Set OrganizationServer to .US for lcx.bambuser.com, or .EU for lcx-eu.bambuser.com dashboard URLs.

val sdkInstance = BambuserSDK(
    applicationContext = this,
    organizationServer = OrganizationServer.US, // or OrganizationServer.EU 
)

val collectionInfo = BambuserCollectionInfo.Playlist(
    containerId = "$containerId",
    pageId = "$pageId",
    orgId = "$orgId",
)

// suspended function that needs to run under a coroutine scope 
// the function can throw an exception if the request failed
lifecycleScope.launch {
    try {
        val collection = sdkInstance.getShoppableVideoPlayerCollection(collectionInfo)
        collection.videoIdList.forEach { videoId ->
                    sdkInstance.GetLShoppableVideoView(
                        videoConfiguration = BambuserVideoPlayerConfiguration(
                            events = listOf("*"),
                            configuration = shoppableVideoConfigurations,
                            videoType = BambuserVideoAsset.Shoppable(videoId),
                        ),
                        videoPlayerDelegate = object : BambuserVideoPlayerDelegate {
                            override fun onNewEventReceived(
                                playerId: String,
                                event: BambuserEventPayload,
                                viewAction: ViewActions
                            ) {
                                // Handle events received  
                            }

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


// Access pagination info
val currentPage = collection.pagination?.page
val totalPages = collection.pagination?.totalPages
val pageSize = collection.pagination?.pageSize
val totalItems = collection.pagination?.total

note

For pageId, you should only pass the name of the page in the host app. i.e **home**/, **product-details**/, **recommendation**, etc. The SDK, will prefix the pageId with http://bambuser.sdk/ to create a unique identifier for the Bamhub. If you have multiple apps with the same organization, you can use packageName parameter in BambuserCollectionInfo.Playlist to differentiate. For multiple playlist in a same page, you can use the same pageId with unique container IDs.

Get videos for a particular SKU:

// Initialize the Bambuser video player with the server region
// You can choose between OrganizationServer.US or OrganizationServer.EU based on your region

val sdkInstance = BambuserSDK(
    applicationContext = this,
    organizationServer = OrganizationServer.US, // or OrganizationServer.EU 
)

val collectionInfo = BambuserCollectionInfo.SKU(
    orgId = "$orgId",
    sku = "$productSKU", 
)

// suspended function that needs to run under a coroutine scope 
// the function can throw an exception if the request failed
lifecycleScope.launch {
    try {
        val collection = sdkInstance.getShoppableVideoPlayerCollection(collectionInfo)
        collection.videoIdList.forEach { videoId ->
                    sdkInstance.GetLShoppableVideoView(
                        videoConfiguration = BambuserVideoPlayerConfiguration(
                            events = listOf("*"),
                            configuration = shoppableVideoConfigurations,
                            videoType = BambuserVideoAsset.Shoppable(videoId),
                        ),
                        videoPlayerDelegate = object : BambuserVideoPlayerDelegate {
                            override fun onNewEventReceived(
                                playerId: String,
                                event: BambuserEventPayload,
                                viewAction: ViewActions
                            ) {
                                // Handle events received  
                            }

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

// Access pagination info
val currentPage = collection.pagination?.page
val totalPages = collection.pagination?.totalPages
val pageSize = collection.pagination?.pageSize
val totalItems = collection.pagination?.total

Load video with VideoID

// Initialize the Bambuser video player with the server region
// You can choose between OrganizationServer.US or OrganizationServer.EU based on your region

val sdkInstance = BambuserSDK(
    applicationContext = this,
    organizationServer = OrganizationServer.US, // or OrganizationServer.EU 
)

sdkInstance.GetLShoppableVideoView(
    videoConfiguration = BambuserVideoPlayerConfiguration(
        events = listOf("*"),
        configuration = shoppableVideoConfigurations,
        videoType = BambuserVideoAsset.Shoppable(videoId),
    ),
    videoPlayerDelegate = object : BambuserVideoPlayerDelegate {
        override fun onNewEventReceived(
            playerId: String,
            event: BambuserEventPayload,
            viewAction: ViewActions
        ) {
            // Handle events received  
        }

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

                
  

Delegate Protocol

The BambuserCommerceSDK provides the BambuserVideoPlayerDelegate an interface for handling communications from a Bambuser video player instance. By implementing this interface, your class can receive callback messages when new events occur or errors are encountered.

Available Methods:

BambuserVideoPlayerDelegate
val delegate = videoPlayerDelegate = object : BambuserVideoPlayerDelegate {
    override fun onNewEventReceived(
        playerId: String,
        event: BambuserEventPayload,
        viewAction: ViewActions
    ) {
        // Handle events
    }

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

For more detailed information please check our Github Repo

Conversion Tracking

Bambuser Conversion Tracking for Shoppable Videos gives you the most value out of your Shoppable videos performance statistics. The Bambuser Conversion tracker enables merchants to attribute the relevant conversions to the Shoppable videos.

To track conversions within the BambuserCommerceSDK, utilize the track function provided by the BambuserPlayerView. This function transmits necessary data sets to Bambuser Analytics.

lifecycleScope.launch {
    sdkInstance.track(
        eventName = "purchase",
        data = mapOf(
            "purchase" to mapOf(
                "id" to "abcd",
                "subtotal" to 70.99,
                "currency" to "USD",
                "total" to 74.98,
                "tax" to 14.2,
                "shippingCost" to 3.99,
                "shippingMethod" to "Store pickup",
                "coupon" to "SUMMER_SALE"
            ),
            "products" to listOf(
                mapOf(
                    "id" to "314-7216-102",
                    "name" to "Tennis Shoe Classic - Size 10",
                    "image" to "https://example.com/images/314-7216-102.jpg",
                    "price" to 70.99,
                    "currency" to "USD",
                    "quantity" to 1,
                    "brand" to "Plausible Co.",
                    "category" to "Footwear > Sports > Tennis",
                    "location" to "https://example.com/products/314-7216"
                ),
            ),
        ),
    )
}

To log an event, you must supply and include additional data as a map with string keys and values of any type Map<String, Any>. Note that the example format is for illustrative purposes only. To log an event, you must supply and include additional data as a map with string keys and values of any type Map<String, Any>.

Note that the example format is for illustrative purposes only.
For the precise data structure required for each event, please refer to our Shopper Events Tracking documentation, where you also find details about fields and types for Transaction and Product objects.

Configuration and Functions

To find the available configuration options for the Preview Player, please refer to Preview API Reference

To find the available configuration and functions for the Video Player in detail, please refer to Bambuser Player API Reference

Bambuser Social Commerce SDK Android

Overview​

Requirements

Installation​

Player Initialization​

Setup​

Create Video Configuration​

Delegate Protocol​

Conversion Tracking​

Configuration and Functions​