Skip to main content

Bambuser Social Commerce SDK iOS

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

This SDK is built using Xcode 16 with the Swift 6 toolchain but remains compatible with Swift 5. Ensure you have the correct version installed for compatibility.

  • Xcode 16 (or later)
  • Swift 5 toolchain
  • iOS 15.6+ supported

Important: Add -ObjC Linker Flag

To ensure full functionality of the SDK, you must add the -ObjC flag to your app target.


img

Installation​

Swift Package Manager (SPM)

You can integrate the SDK using Swift Package Manager. Add the following dependency to your project:

dependencies: [
    .package(url: "https://github.com/bambuser/bambuser-commerce-sdk-ios", from: "2.0.0")
]

Please check our latest release versions here


Manual Installation

If you prefer to integrate the SDK manually, follow these steps:

  • Download BambuserCommerceSDK.xcframework from releases page
  • Drag and drop xcframework file to your project

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.

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

let videoConfiguration: [String: Any] = [
        "thumbnail": [
            "enabled": true,
            "showPlayButton": true,
            "contentMode": "scaleAspectFill",
            "preview": nil
        ],
        "previewConfig": [:],
        "playerConfig": [
            "buttons": [
                "dismiss": "event",
                "product": "none"
            ]
        ]
    ]

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

// Import the SDK
import BambuserCommerceSDK

// Initialize the Bambuser video player with the server region
// You can choose between .US or .EU based on your region
let videoPlayer = BambuserVideoPlayer(server: .US) // or .EU

let videoContainerInfo = BambuserShoppableVideoPlaylistInfo(
    orgId: "xxx",
    pageId: "xxx",
    playlistId: "xxx",
    title: "xxx"
)

let config = BambuserShoppableVideoConfiguration(
    type: .playlist(videoContainerInfo),
    events: ["*"],
    configuration: videoConfiguration
)
let views = try await bambuserPlayer.createShoppableVideoPlayerCollection(
    videoConfiguration: config,
    page: 1, // Pass value of page to fetch
    pageSize: 15
)

// Access pagination info
let currentPage = result.pagination.page
let totalPages = result.pagination.totalPages
let pageSize = result.pagination.pageSize
let totalItems = result.pagination.total

// Bind views to your UI
setupUI(for: views)
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/ and the host app bundleID to create a unique identifier for the Bamhub. For multiple playlist in a same page, you can use the same pageId with unique playlist IDs.

Get videos for a perticular SKU:

// Import the SDK
import BambuserCommerceSDK

// Initialize the Bambuser video player with the server region
// You can choose between .US or .EU based on your region
let videoPlayer = BambuserVideoPlayer(server: .US) // or .EU

let videoContainerInfo = BambuserShoppableVideoSkuInfo(
    orgId: "xxx",
    sku: "xxx"
)

let config = BambuserShoppableVideoConfiguration(
    type: .sku(videoContainerInfo),
    events: ["*"],
    configuration: videoConfiguration
)

let views = try await bambuserPlayer.createShoppableVideoPlayerCollection(
    videoConfiguration: config,
    page: 1, // Pass value of page to fetch
    pageSize: 15
)

// Bind views to your UI
setupUI(for: views)

// Access pagination info
let currentPage = result.pagination.page
let totalPages = result.pagination.totalPages
let pageSize = result.pagination.pageSize
let totalItems = result.pagination.total

Load video with VideoID

// Import the SDK
import BambuserCommerceSDK

// Initialize the Bambuser video player with the server region
// You can choose between .US or .EU based on your region
let videoPlayer = BambuserVideoPlayer(server: .US) // or .EU

let config = BambuserShoppableVideoConfiguration(
    type: .videoId("xxx"),
    events: ["*"],
    configuration: videoConfiguration
)

shoppableVideo = try await bambuserPlayer.createShoppableVideoPlayer(
    videoConfiguration: config
)
// Bind views to your UI
setupUI(for: views)

Delegate Protocol​

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

Available Methods:

BambuserVideoPlayerDelegate
class ViewController: BambuserVideoPlayerDelegate {
    func onNewEventReceived(id: String, event: BambuserEventPayload) {
        print("Player \(id) sent event: \(event)")
    }

    func onErrorOccurred(id: String, error: Error) {
        print("Error in player \(id): \(error.localizedDescription)")
    }

    func onVideoStatusChanged(_ id: String, state: BambuserVideoState) {
        print("Player \(id) changed state to: \(state)")
    }

    func onVideoProgress(_ id: String, duration: Double, currentTime: Double) {
        print("Player \(id) progress: \(currentTime)/\(duration) seconds")
    }
}

For more detailed infomation please check our Github Repo

Conversion Tracking​

Bambuser Conversion Tracking for Live Video Shopping gives you the most value out of your Live Shopping performance statistics. The Bambuser Conversion tracker enables merchants to attribute the relevant conversions to the LiveShopping shows. The number of attributed sales will be available on the stats page of each show.

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

let response = try? await self.playerView.track(
    event: "purchase", 
    with: [
      "transaction": [
        "id":"abcd",
        "subtotal":70.99,
        "currency":"USD",
        "total":74.98,
        "tax":14.2,
        "shippingCost":3.99,
        "shippingMethod":"Store pickup",
        "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":"Plausible Co.",
              "category":"Footwear > Sports > Tennis",
              "location":"https://example.com/products/314-7216"
          ]
        ]
    ]
)

To log an event, you must supply and include additional data as a dictionary with string keys and values of any type ([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 Github Repo.

Configuration and Functions:​

To find the detailed configuration and functions please refer to Bambuser Player API Reference