Integration guide

Introduction

Embed Bambuser Shoppable Video on your website effortlessly using standard HTML Web Components.

The <bam-playlist> web component renders a series of shoppable videos on any website with plenty of flexibility that allows you to style them to match your brand. Each <bam-playlist> will be populated with videos either selected automatically or handpicked by you or your staff.

<bam-playlist org-id="your-org-id"></bam-playlist>

Integration Steps

1. Load the Bambuser script on your website

Global workspaces
EU workspaces

For Bambuser workspaces on the Global dashboard, put the following script tag either in the <head> or <body> tags of your website.

<script async src="https://lcx-embed.bambuser.com/default/embed.js"></script>

For Bambuser workspaces on the EU dashboard, put the following script tag either in the <head> or <body> tags of your website.

<script async src="https://lcx-embed-eu.bambuser.com/default/embed.js"></script>

Where's my workspace located?

If you log in to your workspace on lcx.bambuser.com, use the Global script.

If you log in to your workspace on lcx-eu.bambuser.com, use the EU script.

Already a user?

If you have Bambuser Live shopping shows on your webpage, you already have the script on your site!

Important: Use the Official Bambuser Script

You should use the official Bambuser embed script (e.g., https://lcx-embed.bambuser.com/default/embed.js) instead of hosting a local or modified version. Self-hosted or outdated copies can cause problems like incorrect price rendering, missing features, or broken functionality because they do not receive our ongoing updates. The official script is required for:

Access to the Latest Features: It keeps your integration current with new enhancements and improvements we roll out regularly.
Reliability and Stability: It’s fully tested and maintained by us, preventing errors that arise from outdated or untested code.

2. Position the playlist on your page(s)

Place the web component where the playlist should be by adding a <bam-playlist> in the HTML of your page. Once playlists has been successfully added to your page(s), you can populate the playlists with videos via your workspace.

<bam-playlist org-id="your-org-id"></bam-playlist>

What's my org-id?

You'll find your org-id in the URL of your workspace:

3. Configuring playlist layout and behavior

Below is the options available for configuration of the <bam-playlist> HTML element. Multiple options can be enabled by adding them one after the other to the <bam-playlist> element.

<bam-playlist org-id="your-org-id" autoplay="hover" mode="grid"></bam-playlist>

Note that only org-id is required, the rest are optional.

Not a fan of code?

You can also configure playlists from the "Pages" section in your workspace.

Name	Options	Description
org-id (required)		Your workspaces `org-id`, can be found in the URL when you're logged in to the workspace.
playlist-id (optional)		Playlists are automatically assigned an ID based on their sequence on the page. The first `<bam-playlist>` on the page, will be given `playlist-auto-id-0`, the second `playlist-auto-id-1`, and so on. If you prefer to have more control over the playlist IDs, you can assign a custom ID by using the `playlist-id` attribute within the `<bam-playlist>` element. To apply this custom playlist ID, you will also need to manually override it in the dashboard within Playlist Settings -> Advanced Settings -> Playlist Id. Read more on Multiple Playlists on One page
video-ids (optional)		Create static playlists with specific videos. Provide a comma-separated list of video IDs that will be displayed in the playlist. Example: `<bam-playlist video-ids="puv_qLTxiftQPcJYDAxXuxsgTh,puv_J2VZRPAV1FqWDqeRvWuZkz"> </bam-playlist>` Video IDs To find video IDs, on the Bambuser Shoppable Video dashboard, in the Videos page click on a video. Then the Video ID should be availeble in the URL in the browser addressbar as below: `https://lcx.bambuser.com/YOUR_ORG_ID/on-demand/videos/YOUR_VIDEO_ID/setup`
autoplay (optional)	`hover` (default) `cascade`	Autoplay videos in the playlist. hover ‐ Play when the mouse cursor hovers over a player. cascade ‐ Play a few seconds of each video sequentially.
mode (optional)	`grid` (default) `row` `fab`	Display mode. grid ‐ Render players in a gird (fills available horizontal space and expands downwards). row ‐ Render all players on a single row (scrolling sideways). fab ‐ Placing the players to be fixed to the bottom right corner of the page. Only one player is presented at a time.
player-fit (optional)	`same-width` (default) `same-height` `exact-size` `fill-parent`	Specify the relative size of the players. This is useful when videos have different aspect ratios. same-width ‐ Render all players based on `--bam-player-width`, while height is determined dynamically same-height ‐ Render all players based on `--bam-player-height`, while width is determined dynamically exact-size ‐ Renders all players based on both `--bam-player-width` & `--bam-player-height` fill-parent ‐ Renders all players by using neither `--bam-player-width` & `--bam-player-height`. Requires either `soft-limit="1"` or `mode="single"`.
player-justify (optional)	`left` (default) `right` `center`	Specify the alignment of the players in the playlist. left ‐ Align players to the left. right ‐ Align players to the right. center ‐ Align players to the center.
focus-mode (optional)	`carousel` (default) `single` `none` `playpause`	Select what happens when a user clicks on a video. carousel ‐ Show players in a full-window "carousel". single ‐ Open players individually in a full-window. none ‐ Do nothing. playpause ‐ play/pause the preview player when clicked/tapped on the playlist without expanding the player.
soft-limit (optional)	Positive number. If not provided, all players will be shown.	Limit the number of players shown in a grid/row. Does not affect the number of players visible inside the carousel. Has no effect on `mode=fab`.
zoom-on-hover (optional)	`true` (default) `false`	Controls if a player should "zoom" when hovered by a mouse cursor. true ‐ playlist should "zoom" when hovered by a mouse cursor. false ‐ playlist should not "zoom" when hovered by a mouse cursor.
cookie-domain (optional)		Defines the domain used for conversion tracking cookies; e.g. `.example.com` See Conversion tracking for more information.
cookie-ttl-days (optional)		Defines the time-to-live used for conversion tracking cookies; e.g. `20` See Conversion tracking for more information.
start-focused (optional)	`true` `false` (default)	If set to "true", the playlist will expand (to either carousel or single-mode) immediately.
start-muted (optional)	`true` `false` (default)	If set to "true", when a user focuses on a player by tapping on it, playback will start muted.
product-action (optional)	`true` (default) `false`	If false, no action card will be shown on the previews in the playlist.
query (optional)	`none`	The `query="none"` attribute, disables population of Automatic Playlist based on product SKU.
player-settings (optional)	See Player settings below for options.	Specific settings for how players in the playlist should be presented and behave.

When using mode="fab"

If multiple FABs are published on the same page, FABs from Live content will always take precedence over Shoppable Video FABs. Also, you can only have one bam-playlist set to mode="fab" per page at any time. When bam-playlist is configured as a FAB the player-fit option is forced to exact-size.

Player settings

Below are additional settings that can be used to toggle or configure various elements inside the individual players. These are enabled by adding name-of-setting:value in the player-settings attribute of the <bam-playlist>.

<bam-playlist org-id="your-org-id" player-settings="products:true"></bam-playlist>

Multiple settings can be added by stringing them together separated by a semicolon (;).

<bam-playlist org-id="your-org-id" player-settings="products:true;title:false"></bam-playlist>

Name	Options	Description
products (optional)	`true` (default) / `false`	Controls whether products associated with the video should be shown on top of the players in the playlist. true ‐ Products for the videos are presented on top of the players in the playlist. false ‐ Products for the videos are hidden in the playlist.
productCardMode (optional)	`default` (default) / `thumbnail` / `full`	Controls the layout of product cards in the player. default ‐ Responsive mode. thumbnail ‐ Show only thumbnail image. full ‐ Show thumbnail and text.
title (optional)	`true` (default) / `false`	Controls the visibility of the video title. true ‐ Title text is visible in playlist. false ‐ Title text is hidden in playlist.
overlayTextWrap (optional)	`true` (default) / `false`	Controls whether the text in the overlay should wrap or overflow. true ‐ Text in the playlist should wrap. false ‐ Text in the playlist should overflow.

4. Styling the playlist with CSS variables

The playlist appearance can be easily styled to match your brand using CSS variables.

Here's how to style the playlist:

Define CSS Variables: CSS variables can be defined within a <style> block in your HTML file. These variables will control the appearance of the playlist
Apply CSS Variables: The playlist will automatically use these variables to adjust its styling. Change sizes, fonts and other styles by updating the values of the CSS variables.

Example:

:root {
  --bam-playlist-gap: 10px;
  --bam-player-overlay-font-family: Courier;
}

CSS variable name	Description	Type	Default value
`--bam-player-corner-radius`	Set the corner radius of players.	pixel	0px
`--bam-player-width`	Control the width of players (default is the original size of the video).	pixel	auto
`--bam-player-height`	Control the height of players (default is the original size of the video).	pixel	auto
`--bam-player-overlay-font-family`	Choose which font to use for the title overlay.	string	sans-serif
`--bam-player-overlay-font-weight`	Control the weight of the text in the title overlay.	number	400
`--bam-player-thumbnail-size`	Set the size of the product thumbnail.	pixel	68px
`--bam-player-placeholder-color`	Set the color of the placeholder (shown before the video or poster image has loaded).	color	#EEE
`--bam-playlist-gap`	Control the horizontal and vertical space between players in a row/grid.	pixel	25px
`--bam-playlist-carousel-corner-radius`	Set the corner radius of players rendered in the carousel mode.	pixel	0px

5. Events

The <bam-playlist> component dispatches events that you can listen to in order to create more interactive experiences. Here's how you can register event listeners and respond to user actions:

Close Event

The close event is emitted when a user closes the player (only carousel mode). This is useful for triggering custom behaviors when the user exits the expanded carousel player.

<script>
  document.querySelector('bam-playlist').addEventListener('close', () => {
    console.log('User closed the player');
    // Run your custom code here
  });
</script>

6. Controlling the playlist programmatically

A playlist can be controlled using JavaScript. Below is a list of available functions.

Function	Description
`scrollForward()`	Scrolls to the next video in the playlist.
`scrollBackward()`	Scrolls to the next video in the playlist.
`expand()`	Expands the playlist to focused (carousel or single mode).

Optimizing site speed

A playlist may cause a layout shift when its videos are loaded. If the playlist is rendered above the fold, this could affect your site speed unless adequately handled.

To avoid layout shifts, set a min-height on the playlist and set the player height using --bam-player-height. Use the same value in both places.

Multiple playlists on one page

It is possible to add multiple playlists to a single page. Each playlist must be associated with its own <bam-playlist> element, meaning you will need to have multiple instanced of <bam-playlist> on that page.

By default, playlists are automatically assigned an ID based on the order in which they appear. The first <bam-playlist> will receive the ID playlist-auto-id-0, the second will be assigned playlist-auto-id-1, and so forth.

Optionally, if you need more precise control over which playlist appears in specific locations, you can define custom playlist IDs for each playlist by. For instance, by adding the attribute playlist-id="bam-playlist-below-header" to the <bam-playlist> element like so:

<bam-playlist playlist-id="bam-playlist-below-header" ></bam-playlist>

You can then link this custom ID to the desired playlist through the "Advanced Settings" in the dashboard, ensuring that the correct playlist is displayed in the right place.

Troubleshooting

Shoppable Videos FAQ

Can we standardize video height and width for all playlists?

Yes, you can standardize playlist configurations via UI or code:

Code:

{/* explicitly set the player width and height */}
<style>
  :root {
    --bam-player-width: 260px;
    --bam-player-height: 500px;
}
</style>

{/* set player-fit to exact-size */}
<bam-playlist  player-fit="exact-size" org-id="YOUR_ORG_ID"></bam-playlist>

UI:

Go to Settings in Shoppable Video.
Set Player Width/Height to your desired size (e.g., 260x500).
Enable the Exact Size option for consistent playlist sizing.

What's the maximum length of a shoppable video?

The maximum video length for the Shoppable Video is 5 minutes.

Introduction​

Integration Steps​

1. Load the Bambuser script on your website​

2. Position the playlist on your page(s)​

3. Configuring playlist layout and behavior​

Player settings​

4. Styling the playlist with CSS variables​

Example:​

5. Events​

Close Event​

6. Controlling the playlist programmatically​

Optimizing site speed​

Multiple playlists on one page​

Troubleshooting​

Shoppable Videos FAQ​