Configuration API Reference

Social Commerce SDK Preview mode reference guide

For every shoppable video you can predefine some configuration in the Social commerce SDK. Currently we are supporting three type of configurations.

• Thumbnail Configuration
• Preview Configuration
• Player Configuration

Example code for a preset configuration

Swift

Shoppable Video Config

let videoConfiguration: [String: Any] = [
    "thumbnail": [
        "enabled": true,
        "showPlayButton": true,
        "contentMode": "scaleAspectFill",
        "preview": nil
    ],
    "previewConfig": ["settings": "products:true; title:false; actions:1;"],
    "playerConfig": [
        "buttons": [
            "dismiss": "event",
            "product": "none"
        ]
    ]
]

Kotlin

Shoppable Video Config

  val shoppableVideoConfigurations = mapOf(
    "thumbnail" to mapOf(
    "enabled" to true, 
    "showPlayButton" to true,
    "showLoadingIndicator" to true,
    "preview" to null, 
    ),
    "previewConfig" to mapOf(
        "settings" to "products:true; title: false; actions:1; productCardMode: thumbnail",
    ),
    "playerConfig" to mapOf(
      "buttons" to mapOf(
          "dismiss" to "event",
          "product" to "event",
      ),
      "currency" to "USD",
    )
  )

Thumbnail Configuration

The thumbnail dictionary in the video configuration controls how the video placeholder (thumbnail) behaves before playback begins.

Swift

  "thumbnail": [
    "enabled": true,                // If false, no thumbnail will be added at all.
    "showPlayButton": true,         // Displays a play button overlay. Hidden once the video is tapped to play.
    "showLoadingIndicator": true,   // Shows an activity spinner while the video is loading. Hidden when playback starts.
    "contentMode": "scaleAspectFill", // Defines how the thumbnail image fits inside the view.
    "preview": nil                  // Optional custom image URL. Defaults to the thumbnail set in the Bambuser dashboard if nil.
  ]

contentMode values:

• "scaleToFill" – Stretches the image to completely fill the view. May distort the aspect ratio.
• "scaleAspectFit" – Scales the image to fit within the view while maintaining its aspect ratio. May leave padding.
• "scaleAspectFill" – Scales the image to fill the view while maintaining aspect ratio. May crop edges.

Kotlin

  val thumbnail = mapOf(
    "enabled" to true,                // If false, no thumbnail will be added at all.
    "showPlayButton" to true,         // Displays a play button overlay. Hidden once the video is tapped to play.
    "showLoadingIndicator" to true,   // Shows an activity spinner while the video is loading. Hidden when playback starts.
    "preview" to null,                // Optional custom image URL. Defaults to the thumbnail set in the Bambuser dashboard if null.
  )

Preview Configuration

The previewConfig section allow you to customize the appearance and behavior when the video is in preview mode. in other words previewConfig Controls how the player behaves and looks when the video is playing in inline mode.

By default, the videos can be played, the product cards, action cards and title will be visible. But you can also customise the experience with certain configurations.

note

SDK doesn't support any playlist configuration set on Bamhub. As a developer, you need to set the configurations though preview config.

Different Configurations

Show or hide product cards (default on)

products:true

products:false

Swift

"previewConfig": ["settings": "products:true;"]
"previewConfig": ["settings": "products:false;"]

Kotlin

"previewConfig" to mapOf("settings" to "products:true;")
"previewConfig" to mapOf("settings" to "products:false;")

Control the layout of product cards

productCardMode:default

productCardMode:thumbnail

productCardMode:full

Swift

"previewConfig": ["settings": "products:true; productCardMode:default;"]
"previewConfig": ["settings": "products:true; productCardMode:thumbnail;"]
"previewConfig": ["settings": "products:true; productCardMode:full;"]

Kotlin

"previewConfig" to mapOf("settings" to "products:true; productCardMode:default;")
"previewConfig" to mapOf("settings" to "products:true; productCardMode:thumbnail;")
"previewConfig" to mapOf("settings" to "products:true; productCardMode:full;")

Show or hide video title (default on)

title:true

title:false

Swift

"previewConfig": ["settings": "products:false; title: true;"]
"previewConfig": ["settings": "products:false; title: false;"]

Kotlin

"previewConfig" to mapOf("settings" to "products:false; title: true;")
"previewConfig" to mapOf("settings" to "products:false; title: false;")

note

Product card and title cannot be displayed together, if you want to display the title, you need to hide the product card.

Wrap title (default on)

overlayTextWrap:true

overlayTextWrap:false

Swift

"previewConfig": ["settings": "products:false; title: true; overlayTextWrap:true;"]
"previewConfig": ["settings": "products:false; title: true; overlayTextWrap:false;"]

Kotlin

"previewConfig" to mapOf("settings" to "products:false; title: true; overlayTextWrap:true;")
"previewConfig" to mapOf("settings" to "products:false; title: true; overlayTextWrap:false;")

Add product action (default off)

productAction: modal

productAction: drawer

Swift

"previewConfig": [
    "productAction": "modal", //drawer
    "settings": "products:true; title: false"
    ],
"playerConfig": [
    "buttons": [
        "product": "inline"
    ]
]

Kotlin

"previewConfig" to mapOf(
  "productAction" to "modal",
  "settings" to "products:false; title: false;",
)
"playerConfig" to mapOf(
  "buttons" to mapOf(
    "product" to "inline",
  )
)

note

Product action is off by default in the Inline mode, and you will only receive the event notification if a product is tapped with the product information. To enable the above setup you also need to set the playerConfig button configuration as "product": "inline"

Player Configuration

Defines in-player UI behavior such as buttons, actions, and overlays during expanded mode.

Customizing Player Behavior and UI

Beyond content, you can customize the player's behavior and appearance by modifying the BambuserVideoConfiguration object.

Property Name	Type	Description
autoplay	Bool	Whether the video should start playing automatically. Defaults to true.
muteOnAutoplay	Bool	If autoplay is true, the video will be muted on start. Defaults to true.
loop	Bool	Whether the player should loop back to the first video when the playlist ends.
showControls	Bool	Controls the visibility of player controls such as play/pause and fullscreen.
tintColor	UIColor	The color used for interactive elements on the player, such as buttons.

Example of a custom configuration:

let videoConfiguration: [String: Any] = [
    "thumbnail": [
        "enabled": true,
        "showPlayButton": true,
        "contentMode": "scaleAspectFill",
        "preview": nil
    ],
    "previewConfig": [:],
    "playerConfig": [
        "buttons": [
            "dismiss": "event",
            "product": "none"
        ],
        // Additional custom configurations
        "autoplay": false,
        "loop": true,
        "showControls": true,
        "tintColor": "#9370DB" // Using hex string for color
    ]
]

You can find the configuration attributes in Player API Reference page in Live.