Skip to main content

Player API reference

Bambuser player API reference guide

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

<head>
  <script>
    window.onBambuserLiveShoppingReady = player => {
      // player = Bambuser Player API
    };
  </script>
</head>

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

caution

You should define the onBambuserLiveShoppingReady method before you call initBambuserLiveShopping to initialize any instances of the player when embedding the code snippet.

Constants​

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

player.BUTTON​

Used to dictate the functionality of certain buttons inside the player. It includes the below behavior options.

For player configurations in web/JavaScript, the constants (e.g., player.BUTTON.CLOSE) are used, while in Swift and Kotlin the string values (e.g., "close") are used.

Button behavior options​

Web SDK Behavior
player.BUTTON.AUTO"auto"The default behavior (actual behavior depending on context).
player.BUTTON.CLOSE"close"Close the player overlay.
player.BUTTON.LINK"link"(Web only) The button should behave like a link, relative to the current context. Opens the product URL/ checkout URL in a new browser tab.
player.BUTTON.MINIMIZE"minimize"Minimize the player and act accordingly for minimized context.
player.BUTTON.NONE"none"Does nothing, and the button may be hidden depending on the context.
player.BUTTON.EVENT"event"Triggers an event that can be handled by your custom event handler.

Usage example:

  player.configure({
    buttons: {
      // Set checkout button behavior using a constant
      checkout: player.BUTTON.MINIMIZE,
    },
  });

player.MINIMIZED_POSITION​

Contains the available initial positions of the mini-player.

For configurations in web/JavaScript, the constants (e.g., player.MINIMIZED_POSITION.BOTTOM_RIGHT) are used, while in Swift and Kotlin player configurations, the string values (e.g., "bottom_right") are used.

The default position is bottom right.

Web SDK
player.MINIMIZED_POSITION.BOTTOM_RIGHT"bottom_right"
player.MINIMIZED_POSITION.BOTTOM_LEFT"bottom_left"
player.MINIMIZED_POSITION.TOP_LEFT"top_left"
player.MINIMIZED_POSITION.TOP_RIGHT"top_right"

Usage example:

player.configure({
  // Set the Miniplayer initial position using a position constant
  minimizedPosition: player.MINIMIZED_POSITION.BOTTOM_RIGHT,
});

player.EVENT​

Contains all events that can be emitted from the player.

Web / SDK Trigger
player.EVENT.ADD_TO_CARTAn item was added to users' in-player cart. Consider adding the same item to your on-site cart. The event contains property sku describing the added product.
player.EVENT.CHECKOUTThe user pressed the checkout button from the player cart view.
player.EVENT.CLOSEThe user closed the player.
player.EVENT.PROVIDE_PRODUCT_DATAThe player will (at the time of initiating the player and sometime in the future depending on the context) display a product. The player requests you to provide all necessary product data using player.updateProduct().
player.EVENT.PLAYER_SWIPE_DOWNUser made a swipe down gesture.
player.EVENT.PLAYER_SWIPE_LEFTUser made a swipe left gesture.
player.EVENT.PLAYER_SWIPE_RIGHTUser made a swipe right gesture.
player.EVENT.PLAYER_SWIPE_UPUser made a swipe up gesture.
player.EVENT.READYThe player GUI has been loaded and is ready for interactions by the user.
player.EVENT.SHOW_ADD_TO_CALENDARAdd-to-calendar dialog should open.
player.EVENT.SHOW_PRODUCT_VIEWA product is clicked (whether from the product list or highlighted product).
player.EVENT.SHOW_PRODUCT_LISTProduct list should open.
player.EVENT.SHOW_SHAREShare dialog should open.
player.EVENT.SYNC_CART_STATEWhenever the viewer navigates back to the player, the player requests an update regarding which items should be displayed in the user's in-player cart.
player.EVENT.UPDATE_ITEM_IN_CARTUser has changed the quantity of a product in the in-player cart, consider updating the on-site cart.
player.EVENT.NOTIFY_URL_CHANGEThis is called when an action in the player component triggers your webpage to navigate to a specific page.

Usage example:

On Web, use player.on() and the constant variable (e.g., player.EVENT.READY)

// Register a event handler for `close` event using event constants
player.on(player.EVENT.CLOSE, () => {
  console.log("Player was closed");
});

Methods​

Methods available in the player API. Below you can find each method in detail including examples for each one.

player.close()​

Usage example:

// Close the current player and remove it from the DOM
player.close();

player.configure(configuration)​

The player can be configured to meet your needs using the configure method.

If implementing cart integration, some configurations like currency and locale, are required for the player to correctly display products and translations, whilst others are optional.

Usage example:

player.configure({
currency: "USD",
locale: "en-US",
buttons: {
dismiss: player.BUTTON.MINIMIZE,
checkout: player.BUTTON.MINIMIZE,
},
});

configuration.locale​

Sets the global locale of the player, defining the language and region for products, cart, and checkout integration. The value must be a string in the format languageCode-countryCode (e.g., en-US for English in the United States). If not set, the player uses the default locale from your Bambuser workspace.

To support a locale, it must first be added in Bam Hub under Settings > Translations. If the specified locale is not available, the player falls back to the default locale defined in your Bam Hub.

Usage example:

player.configure({
  locale: "en-US",
});

Dynamic Locale Example:

const userLocale = yourMethodToGetUserLocale(); // e.g., "sv-SE" for Swedish 
player.configure({
  locale: userLocale,
});

Note that translation updates may take up to 30 minutes to reflect due to caching.

configuration.currency​

Sets the global currency of the player. The value should be of type string and contain the three-letter currency code, e.g. USD. If none other is specified, this value is used for both products, cart, and checkout integration.

Usage example:

player.configure({
  currency: "USD",
});

configuration.buttons​

Configures how buttons behave in the player.

Each button can be set to follow a behavior specified in the BUTTON constants section.

List of configurable buttons
ContentDescriptionAvailable behaviors
dismissThe button in the upper right corner of the playerplayer.BUTTON.CLOSE
player.BUTTON.MINIMIZE
player.BUTTON.NONE
checkoutThe checkout buttonplayer.BUTTON.LINK
player.BUTTON.MINIMIZE
productClick on a product reference, in the highlight or the product listplayer.BUTTON.LINK
player.BUTTON.MINIMIZE
player.BUTTON.NONE

Usage example:

  player.configure({
    buttons: {
      dismiss: player.BUTTON.CLOSE,
    },
  });
More examples of button configuration

  • Enable the Miniplayer

    player.configure({
      buttons: {
        dismiss: player.BUTTON.MINIMIZE,
      },
    });

  • Enable the Miniplayer & Minimize when checkout button is clicked

    player.configure({
      buttons: {
        dismiss: player.BUTTON.MINIMIZE,
        checkout: player.BUTTON.MINIMIZE,
      },
    });

  • Enable Miniplayer & Minimize the player when a product is clicked

    player.configure({
      buttons: {
        product: player.BUTTON.MINIMIZE,
      }
    });

configuration.audioTrackLocale​

Sets the default audio track language when dubbed audio is enabled. This enables the player to automatically select and play the appropriate dubbed language when multiple audio options are available, eliminating the need for users to manually choose a language.

Usage example:

  player.configure({
    audioTrackLocale: "de-DE", // Sets German dubbed audio as the default where available
  });

configuration.shareTargets​

This parameter overrides all the underlying default share targets:

Available Share Targets
  • linkedin (default)
  • twitter (default)
  • whatsapp (default)
  • email (default)
  • facebook (default)
  • instapaper
  • line
  • liveJournal
  • mailRu
  • odnoklassniki
  • pocket
  • reddit
  • telegram
  • tumblr
  • viber
  • vk
  • weibo
  • workplace

Usage example

player.configure({
	shareTargets: ['reddit', 'telegram'],
});

configuration.minimizedPosition​

Configures the initial position of the mini-player.

List of available positions
  • player.MINIMIZED_POSITION.BOTTOM_RIGHT - the default position
  • player.MINIMIZED_POSITION.BOTTOM_LEFT
  • player.MINIMIZED_POSITION.TOP_LEFT
  • player.MINIMIZED_POSITION.TOP_RIGHT

Usage example

player.configure({
  minimizedPosition: player.MINIMIZED_POSITION.BOTTOM_LEFT,
});

configuration.checkoutOnCartClick​

Configures the player to emit the player.EVENT.CHECKOUT event when clicking any of the buttons which would present the cart in the player, instead of opening the player's internal cart.

Usage example

  player.configure({
    checkoutOnCartClick: true,
  });

configuration.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. If shareBaseUrl is undefined, null, or '' the share URL will default to window.location.href.

Usage example

  player.configure({
    shareBaseUrl: 'https://example.com/live-shopping?referer=joe',
  });

configuration.trackingTags​

Add a list of custom tracking tags which should be included to all tracking events dispatched by the player.

Usage example

  player.configure({
    trackingTags: [{ key: 'memberId', value: '123-abc' }],
  });

configuration.allowShareAutoplay​

Allow or disable autoplay when opening shared URLs.

If allowShareAutoplay is set to false the share URL presented in the player will not include the ?autoplayLiveshopping=[showId] query parameter. (Learn more about Autoplay)

Default value: true

Usage example

  player.configure({
    allowShareAutoplay: false,
  });

configuration.enableFirstPartyCookies​

Enables/disables setting of first-party cookies by the player.

If a user declined cookies through your cookie consent, you may need to prevent our player from setting the cookies using this configuration.

Default value: true 

player.configure({  
  enableFirstPartyCookies: false,
});
caution

** This flag should be unset only for visitors who declined the cookies. **

The Conversion Tracker can not collect purchase data from users who do not have the cookies set.

Usage example

Here we used an imaginary method (hasDeclinedCookies) to check if the cookies have been declined before disabling cookies. You need to replace your own logic.

player.configure({
  enableFirstPartyCookies: !hasDeclinedCookies()
});

configuration.cookie​

An object including settings for first-party cookies set by the player.

Available properties:

  • domain
    Sets the domain attribute of the first-party cookies.
  • activityCookieTTLDays
    Changes the expiration time for Conversion Tracking cookies (_bamls_shid and _bamls_lits) and consequently the duration of the time that purchases are being tracked

Usage example

player.configure({
  cookie: {
    domain: '.example.com', // Cookies can also be accessed by all subdomains ex. checkout.example.com
    activityCookieTTLDays: 1, // Will only track conversions for 1 day after interaction with the show
  }
});

configuration.trimPriceTrailingZeros​

Allow to remove the price decimals when they are equal to zero, disabled by default.

Usage example

  player.configure({
    trimPriceTrailingZeros: true,
  });

Make the player seek to a specific product appearance reference in the show. The deeplink value to a product appearance can be found in the product appearances REST API endpoints. This deeplink value will become invalid if the video content in specific show is changed, then you should fetch a new player.configuration value to get a valid value.

If you have a unique player.configuration for a specific show you can use this configuration to specifically tell the player which product appearance the player should start playing from. If you do not have a unique configuration then you can pass this deeplink key/value in the JSON object which is used as an argument for initBambuserLiveShopping function call.

Usage example

  player.configure({
    deeplink: "f00ba5@100",
  });

  // or

  window.initBambuserLiveShopping({
    showId: 'show-id',
    deeplink: "f00ba5@100",
  });

configuration.ui​

Hide UI elements when necessary. All hidable elements are listed below:

  • hideActionBar
  • hideAddToCalendar
  • hideCartButton
  • hideCartView
  • hideChatOverlay
  • hideEmojiOverlay
  • hideProductList
  • hideProductView
  • hideShareButton
  • hideShareView

Usage example

player.configure({
  ui: {
    hideAddToCalendar: false,
    hideShareView: false,
  },
});

configuration.experimental​

Configures behavior and functionality of the player using flags. Value is of type object and may contain multiple different flags as properties.

note

All flags available under experimental are subject to change and should be used with caution. When a feature is considered "production ready" we will include it in the general configuration.

Available Experimental Properties
  • chatName string - Sets the chat alias for the user instead of prompting when entering chat
  • hasAcceptedTerms boolean - Disables terms & conditions prompt if set to true

Usage example:

player.configure({
  experimental: {
    chatName: "John D",
    hasAcceptedTerms: true,
  },
});

player.minimize()​

Minimizes the player when invoked.

player.unminimize()​

When the player is minimized, invoking this method maximizes the player.

player.on(eventName, eventHandler)​

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

Usage example:

player.on(player.EVENT.CLOSE, () => {
  console.log("Player was closed");
});

player.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("Close event was triggered");
};

// Register the listener from this point. Any close event
// will trigger the console.log above
player.on(player.EVENT.CLOSE, someEventHandler);

// Removes the registered listener from this point. Close events
// will no longer trigger the console.log
player.off(player.EVENT.CLOSE, someEventHandler);

player.removeAllListeners()​

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

Usage example:

player.on(player.EVENT.CLOSE, () => {
  console.log("Player was closed");
});

player.on(player.EVENT.CHECKOUT, () => {
  console.log("User pressed checkout");
});

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

player.showCheckout(checkoutPageUrl)​

Navigate to a checkout page (or any other pages) when invoked.

This method uses the checkout button configuration to determine how to navigate to the target page. If no configuration is provided, it opens the URL in a new tab.

  • checkout: player.BUTTON.MINIMIZE
    Minimizes the player and opens the link on the same window

  • checkout: player.BUTTON.LINK
    Opens the link in a new tab

Usage example:

player.on(player.EVENT.CHECKOUT, () => {
  player.showCheckout("https://example.com/checkout");
});

player.updateCart(cartData)​

Update the player cart state.

note

Currently, updateCart only supports emptying the cart. This action is useful when the shopper completes the checkout/empties the cart and comes back to the player.

Usage example:

player.on(player.EVENT.SYNC_CART_STATE, () => {
  // Use your method to check if the user has checkout
  if (isOnSiteCartEmpty()) {
    // Emptying the in-player cart
    player.updateCart({
      items: [],
    });
  }
});

player.updateProduct(productId, productFactory)​

Updates all necessary product details that allow the player to properly display a product.

List of arguments
ArgumentsDescriptionType
productIdThe Bambuser generated ID for each product of a show. Found in the PROVIDE_PRODUCT_DATA event payload (event.products).string
productFactoryMethod that should return a finished product.callback

Update product details​

Here is a full example of updating products using the player.updateProduct() method.

player.on(player.EVENT.PROVIDE_PRODUCT_DATA, (event) => {
  event.products.forEach(async ({ ref: sku, url, id: bambuserId }) => {
    const yourProduct = await yourGetProductMethod(sku);

    player.updateProduct(bambuserId, (productFactory) =>
      productFactory

        // -> The .product() method takes a function
        //    returning a product detail object
        .product((productDetailFactory) =>
          productDetailFactory

            // Name of the product
            .name(yourProduct.name)

            // Brand name to display for the product
            .brandName(yourProduct.brand)

            // (Optional) Short product introductory text 
            .introduction(yourProduct.shortDescription)

            // (Optional) Description for the product
            // Supports text as well as HTML string
            .description(yourProduct.description)

            // sku (or any other identifier for your product)
            // NOTE: Should be the same as your product reference
            // defined in Bambuser Workspace
            .sku(yourProduct.productId)

            // Describes which index in the variations list below
            // contains the default variation
            // (e.g. if variations contain colors, and you want to display
            //  the white version of a shirt, send the index for the white variation)
            .defaultVariationIndex(0)

            // -> The .variations() method takes a function
            //    returning an array of variations
            .variations((variationFactory) =>
              yourProduct.colors.map((variation) =>
                // VariationFactory contains a factory returning a new instance of a variation
                variationFactory()
                  // -> (Optional) The .attributes() method takes a function
                  //    defines color attribute for the variation
                  .attributes((attributeFactory) =>
                    attributeFactory
                      // Color name in the variation dropdown selector,
                      .colorName(variation.colorName)

                      // (Optional) Color Hex code e.g. '#7d58ee'
                      .colorHexCode(variation.colorHexCode)
                  )
                  // List of image urls for the variation
                  // ordered the same as you want it displayed
                  .imageUrls(variation.images)

                  // Name of the variation
                  // Shown if colorName is not provided as attribute.
                  .name(variation.name)

                  // sku (or any other identifier for your product)
                  // specific down to this variation
                  .sku(variation.variationId)

                  // -> The .sizes() method takes a function that
                  //    returns an array of sizes
                  .sizes((sizeFactory) =>
                    variation.sizes.map((size) =>
                      // s contains a factory returning a new instance of a variation
                      sizeFactory()
                        // Name of the size
                        // (used in dropdowns)
                        .name(size.name)

                        // Set whether this combination of
                        // variation and size is in stock
                        .inStock(size.quantityInStock > 0)

                        // sku (or any other identifier for your product)
                        // specific down to this size (used for add-to-cart)
                        .sku(size.sizeId)

                        // -> The price method contains a new chain
                        //    defines price for the variation and size combo
                        .price((priceFactory) =>
                          priceFactory
                            // currency to show price in
                            // Optional - overrides the default currency
                            .currency(size.currency)

                            // current price as a number
                            .current(size.current)

                            // (Optional) original price
                            // Used in case the current is a sale price
                            .original(size.original)

                            // (Optional) This set of fields allows showing price per unit, e.g. $77 / 100ml
                            .perUnit(size.perUnit)
                            .unitAmount(size.unitAmount)
                            .unitDisplayName(size.unitDisplayName),
                        )
                    )
                  )
              )
            )
        )
    );
  });
});

Inherit from scraped product​

By default when you hydrate a product using the updateProduct() method, it will create a new empty product. Therefore, it requires you to provide all needed details since the product information previously scraped (or manually inserted) through the workspace will get overridden.

However, Bambuser offers an option to inherit those product information from the scraped product (E.g. name, brand) after creating the new empty product.

Usage Example

To do so, you need to chain inheritFromPlaceholder() to productFactory.

player.on(player.EVENT.PROVIDE_PRODUCT_DATA, (event) =>
  event.products.forEach(({ ref: sku, id: productId, url: publicUrl })   => {
    // Your method to fetch product data
    yourGetProductDataMethod(sku).then((currentProduct) =>
      player.updateProduct(productId, (productFactory) =>
        productFactory
          .inheritFromPlaceholder()
          .product((productDetailFactory) =>
            detailsFactory
              .name(item.title)
              .sku(item.id)
              .brandName(item.vendor)
              .variations(
                (variationFactory) =>
                  // ....
              )
          )
      )
    );
  })
);

Using inheritFromPlaceholder() you will get more functionalities such as overriding product URLs and hiding product. You can read more about that below.

Override products URL​

If you use different domains across different markets, you may sometimes (when you link the player to PDPs) need to update product details with market-specific PDP URLs. It is quite simple to do so if the products share the same SKUs across the markets.

To override the PDP's URL, pass the current market PDP URL to publicUrl(String) method for each product; as highlighted in the example below.

Usage Example

player.on(player.EVENT.PROVIDE_PRODUCT_DATA, (event) =>
  event.products.forEach(({ ref: sku, id: productId, url: publicUrl }) => {
    // Your method to fetch localized product data
    yourMethodThatGetsLocalizedProductData(sku).then((currentProduct) =>
      player.updateProduct(productId, (productFactory) =>
        productFactory
          .inheritFromPlaceholder()
            .publicUrl(currentProduct.url)
      )
    );
  })
);

Hide a product​

You can hide a product from the viewer through the Player API. This feature hides the product from the player

player.on(player.EVENT.PROVIDE_PRODUCT_DATA, function (event) {
  event.products.forEach(({ ref: sku, id: productId, url: publicUrl }) => {
    getLocalizedProductBySku(sku).then((currentProduct) =>
      player.updateProduct(productId, (productFactory) => {
        return productFactory
          .inheritFromPlaceholder()
          .hidden(!currentProduct.isAvailable);
      })
    );
  });
});
Additional Example: Hide product if not available
player.on(player.EVENT.PROVIDE_PRODUCT_DATA, function (event) {
  event.products.forEach(({ ref: sku, id, url }) => {
    yourGetProductMethod(sku).then(item => {
      if (!item.available) {
        // Product is unavailable - Hide the product
        player.updateProduct(id, productFactory => {
          return productFactory
            .inheritFromPlaceholder()
            .hidden(true)
        })
      }
      else {
        // Product is available - Hydrate the product as usual
        player.updateProduct(id, productFactory =>
          productFactory.product(detailsFactory =>
            detailsFactory
              .name(item.title)
              .sku(item.id)
              .brandName(item.vendor)
              .variations(variationFactory =>
                // ....
              ),
          ),
        );
      }
    }
    );
  });
});

callback()​

When handling ADD_TO_CART and UPDATE_ITEM_IN_CART events, callback method is provided as the second argument to the event handler method. You need to use this method in order to let the player know if the operation (add to cart/update cart) was successful or unsuccessful and show a proper message to the viewer.

Success​

callback(true);
// Default message: Added to cart!

Failure​

callback(false);
// Default message: Problem adding product to basket, please try again!

out-of-stock

  callback({
    success: false,
    reason: 'out-of-stock',
  });
  // Default message: The selected size has been sold out!

Custom error message

  callback({
    success: false,
    reason: "custom-error",
    message: "This is my custom error message", //edit this by your choice
  });

setTrackingTags(trackingTags)​

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

Usage example:

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