Widget API reference

Bambuser Widget API reference guide

After setting up your onBambuserWidgetReady handler (example below) you can start customizing the behavior of your widget.

<head>
  <script>
    window.onBambuserWidgetReady = widget => {
      // widget = Bambuser Widget API
    };
  </script>
</head>

caution

Note that the widget object and its properties (constants and methods below) are only accessible within the onBambuserWidgetReady method body.

You should define the onBambuserWidgetReady method before FAB and/or Channels widgets embed snippets.

Constants

A list of available constants to be used throughout the widget integration.

`widget.EVENT.CHANNEL`

Events specific to the Channels widget. Use widget.on() to register an event listener (described further down).

.PRESENT

The Channel widget is rendered inside the embedded container.

Example:

widget.on(widget.EVENT.CHANNEL.PRESENT, (eventData) => {
  console.log('🧩 Triggered event: widget.EVENT.CHANNEL.PRESENT');
  console.log('🧩 Event payload:', eventData);
});

Event payload

Content	Description	Type
`containerId`	Bambuser Channel widget container ID attached to the `data-bambuser-liveshopping-widget-id` attribute	String
`playlists`	List of playlists including details and shows' data.	Array
`locale`	The effective locale code ex. `en-US`	String

.PLAY

Triggered after a user triggers the player by clicking on a show.

Example:

widget.on(widget.EVENT.CHANNEL.PLAY, (eventData) => {
  console.log('🧩 Triggered event: widget.EVENT.CHANNEL.PLAY');
  console.log('🧩 Event payload:', eventData);
});

Event payload

Content	Description	Type
`showId`	ID of the show that is played through Channel	`String`
`showTitle`	Title of the show	`String`
`showStatus`	Could be 'live', 'recorded', 'scheduled', or 'upcoming'	`String`

.SHARE

A show's 'share' button is clicked from the Channel widget.

Example:

widget.on(widget.EVENT.CHANNEL.SHARE, (eventData) => {
  console.log('🧩 Triggered event: widget.EVENT.CHANNEL.SHARE');
  console.log('🧩 Event payload:', eventData);
});

Event payload

Content	Description	Type
`showId`	ID of the show that is played through Channel	`String`
`showTitle`	Title of the show	`String`
`showDescription`	Description of the show	`String`
`showStatus`	Could be 'live', 'recorded', 'scheduled', or 'upcoming'	`String`
`scheduledStartAt`	Scheduled show time to go Live	`String` ( ISO 8601 ) \| `null`
`shareUrl`	Share URL by default uses the current page as the based URL. Configure shareBaseUrl	`String`

.ADD_TO_CALENDAR

The 'add to calendar' button of a show on the Channel widget is clicked.

Example:

widget.on(widget.EVENT.CHANNEL.ADD_TO_CALENDAR, (eventData) => {
  console.log('🧩 Triggered event: widget.EVENT.CHANNEL.ADD_TO_CALENDAR');
  console.log('🧩 Event payload:', eventData);
});

Event payload

Content	Description	Type
`showId`	ID of the show that is played through Channel	`String`
`showTitle`	Title of the show	`String`
`showDescription`	Description of the show	`String`
`showStatus`	Could be 'live', 'recorded', 'scheduled', or 'upcoming'	`String`
`scheduledStartAt`	Scheduled show time to go Live	`String` ( ISO 8601 )
`shareUrl`	Share URL by default uses the current page as the based URL. Configure shareBaseUrl	`String`

`widget.EVENT.FLOATING`

Events specific to the Floating Action Button (FAB). Use widget.on() to register an event listener (described further down).

`.PRESENT`

Emitted on the page load when the FAB widget is present on the page.

Example:

widget.on(widget.EVENT.FLOATING.PRESENT, (eventData) => {
  console.log('🧩 Triggered event: widget.EVENT.FLOATING.PRESENT');
  console.log('🧩 Event payload:', eventData);
});

Event payload

Content	Description	Type
`containerId`	Bambuser FAB widget container ID attached to the `data-bambuser-liveshopping-widget-id` attribute	`String`
`present`	Whether the widget is visible or not	`Boolean`
`showId`	ID of the show presented on the FAB	`String`
`showStatus`	Can be `live` or `recorded`	`String`
`position`	Contains the widget position information	`Object`
`position.initial`	Possible values: `Bottom left` or `Bottom right`. The initial position can be changed through the Widgets > FAB setup page in the workspace.	`String`
`position.offset`	Returns the effective offsets. How to apply custom offsets	`Object`
`position.offset.x`	Effective offset in the X axis.	`Number`
`position.offset.y`	Effective offset in the Y axis.	`Number`

.PLAY
Triggered after a user triggers the player by clicking on the FAB preview video.

Example:

widget.on(widget.EVENT.FLOATING.PLAY, (eventData) => {
  console.log('🧩 Triggered event: widget.EVENT.FLOATING.PLAY');
  console.log('🧩 Event payload:', eventData);
});

Event payload

Content	Description	Type
`containerId`	Bambuser FAB widget container ID attached to the `data-bambuser-liveshopping-widget-id` attribute	`String`
`showId`	ID of the show presented on the FAB	`String`
`showStatus`	Can be `live` or `recorded`	`String`

.NAVIGATE
Triggered after a user clicks on the FAB preview video while a redirection URL is set for FAB. The redirection URL can whether be set in the workspace on through FAB configurations code.

Example:

widget.on(widget.EVENT.FLOATING.NAVIGATE, (eventData) => {
  console.log('🧩 Triggered event: widget.EVENT.FLOATING.PLAY');
  console.log('🧩 Event payload:', eventData);
});

Event payload

Content	Description	Type
`containerId`	Bambuser FAB widget container ID attached to the `data-bambuser-liveshopping-widget-id` attribute	`String`
`showId`	ID of the show presented on the FAB	`String`
`showStatus`	Can be `live` or `recorded`	`String`
`redirection`	Includes the effective redirection details	`Object`
`redirection.url`	URL of the landing page	`String`
`redirection.target`	Redirection target ex: `_self`, `_blank`, `_parent`, or `_top`. (Default: `_self`)	`String`

.DISMISS

Triggered when the FAB is dismissed (hidden). This action is only possible for FAB presenting a recorded show.

Example:
```
widget.on(widget.EVENT.FLOATING.DISMISS, (eventData) => {
  console.log('🧩 Triggered event: widget.EVENT.FLOATING.DISMISS');
  console.log('🧩 Event payload:', eventData);
});
```
Event payload
Content Description Type
containerId Bambuser FAB widget container ID attached to the data-bambuser-liveshopping-widget-id attribute String
showId ID of the show presented on the FAB String
.CONDENSE

Triggered when the FAB is condensed. This action is only possible when FAB is showing a Live video.

Example:
```
widget.on(widget.EVENT.FLOATING.CONDENSE, (eventData) => {
  console.log('🧩 Triggered event: widget.EVENT.FLOATING.CONDENSE');
  console.log('🧩 Event payload:', eventData);
});
```
Event payload
Content Description Type
containerId Bambuser FAB widget container ID attached to the data-bambuser-liveshopping-widget-id attribute String
.EXPAND

Triggered when the FAB is expanded to the preview player from the condensed mode. This action is only possible when FAB is showing a Live video.

Example:
```
widget.on(widget.EVENT.FLOATING.EXPAND, (eventData) => {
  console.log('🧩 Triggered event: widget.EVENT.FLOATING.EXPAND');
  console.log('🧩 Event payload:', eventData);
});
```
Event payload
Content Description Type
containerId Bambuser FAB widget container ID attached to the data-bambuser-liveshopping-widget-id attribute String

Methods

`widget.configure(configuration)`

This method accepts the configuration for your widgets.

widget.configure({
  channel: {
    // Configurations for Channel
  },
  fab: {
    // Configurations for FAB
  },
});

Below are the available configuration options:

Channel

configuration.channel.shareBaseUrl
Overrides the base URL for creating a link to access the show for both Share and AddToCalendar features. The URL must be an absolute path and can include protocol (http:// or https://) and query parameters.

Default: window.location.href

Usage example:
```
widget.configure({
  channel: {
    shareBaseUrl: 'https://example.com/live-shopping?referer=joe',      
  },
});
```
configuration.channel.ui
Hide specific elements of the Channel UI. Here are a list of available properties:
- hideShareButton
- hideShareList
- hideAddToCalendarButton
- hideAddToCalendarList
Usage example:
```
widget.configure({
  channel: {
    ui: {
      hideShareList: true,
      hideAddToCalendarList: true,
    },      
  },
});
```

Floating Action Button (FAB)

configuration.fab.redirection
A redirection URL to navigate user to after clicking on the Floating Action Button (FAB) to play the show. Properties:
- url: A string containing an absolute or relative URL.
  Note that in Bambuser workspace > Widgets > FAB, you can also set a redirection URL that takes precedence over the URL configured here.
- target: Redirection target ex: _self, _blank, _parent, or _top. (Default: _self)
Usage example:
```
widget.configure({
  fab: {
    redirection: {
      url: 'https://mybrand.com/video-shopping',
      target: '_blank',
    },      
  },
});
```

Tracking Tags

configuration.trackingTags

A list of tags which should be included in all tracking events

Usage example:
```
widget.configure({
  trackingTags: [{
    key: 'customerId',
    value: '123-abc',
  }],
});
```

`widget.on(eventName, eventHandler)`

Registers an event listener for any event from the EVENT constants above.

Usage example:

widget.on(widget.EVENT.FLOATING.PRESENT, () => {
  console.log('Floating widget presented');
});

`widget.off(eventName, eventHandler)`

Removes a previously registered event listener from receiving any more events.

note

The second parameter needs to be the same handler method provided at the time of registering the event listener.

Usage example:

// Define an event listener
const someEventHandler = () => {
  console.log('Floating widget dismissed');
};

// Register the listener from this point. Any dismissal event
// will trigger the console.log above
widget.on(widget.EVENT.FLOATING.DISMISS, someEventHandler);

// Removes the registered listener from this point. Dismissal events
// will no longer trigger the console.log
widget.off(widget.EVENT.FLOATING.DISMISS, someEventHandler);

`widget.removeAllListeners()`

Removes all event listeners defined by widget.on() . Use this sparsely and with caution.

Usage example:

widget.on(widget.EVENT.FLOATING.PRESENT, (eventData) => {
  console.log('Floating widget presented', eventData);
});
widget.on(widget.EVENT.FLOATING.DISMISS, (eventData) => {
  console.log('Floating widget dismissed', eventData);
});

// After this point, the above listeners will not be triggered again
widget.removeAllListeners();

`widget.setTrackingTags(trackingTags)`

Adds a list of custom tracking tags to all Bambuser tracking events.

Usage example:

widget.setTrackingTags([
  {
    key: 'customerId',
    value: '123-abc',
  },
  {
    key: 'membership',
    value: 'premium',
  }
]);

Widget API reference

Constants

`widget.EVENT.CHANNEL`

`.PRESENT`

`.PLAY`

`.ADD_TO_CALENDAR`

`widget.EVENT.FLOATING`

`.PRESENT`

`.PLAY`

`.NAVIGATE`

`.DISMISS`

`.CONDENSE`

`.EXPAND`

Methods

`widget.configure(configuration)`

`configuration.channel.shareBaseUrl`

`configuration.channel.ui`

`configuration.fab.redirection`

`configuration.trackingTags`

`widget.on(eventName, eventHandler)`

`widget.off(eventName, eventHandler)`

`widget.removeAllListeners()`

`widget.setTrackingTags(trackingTags)`

Constants​

widget.EVENT.CHANNEL​

.PRESENT​

.PLAY​

.SHARE​

.ADD_TO_CALENDAR​

widget.EVENT.FLOATING​

.PRESENT​

.PLAY​

.NAVIGATE​

.DISMISS​

.CONDENSE​

.EXPAND​

Methods​

widget.configure(configuration)​

configuration.channel.shareBaseUrl​

configuration.channel.ui​

configuration.fab.redirection​

configuration.trackingTags​

widget.on(eventName, eventHandler)​

widget.off(eventName, eventHandler)​

widget.removeAllListeners()​

widget.setTrackingTags(trackingTags)​

Constants

`widget.EVENT.CHANNEL`

`.PRESENT`

`.PLAY`

`.SHARE`

`.ADD_TO_CALENDAR`

`widget.EVENT.FLOATING`

`.PRESENT`

`.PLAY`

`.NAVIGATE`

`.DISMISS`

`.CONDENSE`

`.EXPAND`

Methods

`widget.configure(configuration)`

`configuration.channel.shareBaseUrl`

`configuration.channel.ui`

`configuration.fab.redirection`

`configuration.trackingTags`

`widget.on(eventName, eventHandler)`

`widget.off(eventName, eventHandler)`

`widget.removeAllListeners()`

`widget.setTrackingTags(trackingTags)`