Player API Reference

Bambuser Player API Reference guide

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

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

CAUTION

you should define this method:

  • beforeDOMContentLoadedis triggered on the page
  • before you callinitBambuserLiveShoppingto initialize any instances of the player when embedding the code snippet.

Constants

player.BUTTON

Used to dictate the functionality of certain buttons inside the player.

.AUTO

The default behavior (actual behavior depending on context).

.CLOSE

Close the player. Display matching GUI.

The button should behave like a link, relative to the current context.

.MINIMIZE

Minimize the player and act accordingly for minimized context. Display matching GUI.

.NONE

Does nothing, and the button may be hidden depending on the context.

player.EVENT

Contains all events that may be emitted from the player. Use player.on() to register an event listener (described further down).

.ADD_TO_CART

An 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.

.CHECKOUT

The user pressed the checkout button.

.CLOSE

The user closed the player.

.PROVIDE_PRODUCT_DATA

The player will (now or sometime in the future) display a product. The player requests you to provide all necessary product data using player.updateProduct().

.READY

The player GUI has been loaded and is ready for interactions by the user.

.SYNC_CART_STATE

The player requests an update regarding which items should be displayed in the user's in-player cart.

.UPDATE_ITEM_IN_CART

User has changed the quantity of a product in the in-player cart, consider updating the on-site cart.

Methods

player.close()

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.

Some parameters, like currency and locale, are required for the player to correctly display products and translations, whilst other options are just that - options.

Example Very basic player with US English language and USD currency.

player.configure({
  currency: 'USD',
  locale: 'en-US',
});

configuration.buttons (optional)

Configures how buttons behave in the player.

Each button can be set to follow a behavior specified in the BUTTON constant above.

All configuration buttons

  • checkout - the checkout button
  • dismiss - the button in the upper right corner of the player
  • product - click on a product reference, in the highlight or the product list

Example

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

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.

Example

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

configuration.experimental (optional)

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 checkout button
  • hasAcceptedTerms "boolean" - Disables terms & conditions prompt if set to true

Example

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

configuration.locale

Sets the global locale of the player. The value should be of type string and contain country code combined with language code like so: en-US. If none other is specified, this value is used for both products, cart, and checkout integration.

Example

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

Full Example

The player with the English language and USD currency. Buttons configured to minimize the player instead of closing it when going to checkout or navigating on the page.

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

player.on(eventName, eventHandler)

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

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.

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.

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)

Show a checkout page residing at checkoutPageUrl in the current player context.

Example

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

player.updateCart(cartData)

Update the player cart with new items.

NOTE

Currently, updateCart does not support anything more than emptying the cart. We are working on providing a way for you to fully control the in-player cart.

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)

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

Arguments

  • productId {string} - The player's internal ID for the product. Found in the PROVIDE_PRODUCT_DATA event.
  • productFactory {callback} - Method that should return a finished product.

Example
Very basic example for a product with a single color and a single size. Currency and locale will default to the ones specified using the player.configure() method and in-stock status will always be true.

player.on(player.EVENT.PROVIDE_PRODUCT_DATA, event => {
  event.products.forEach(({ ref: sku, id: productId, url: publicUrl }) => {


    // Use the references provided above to fetch product details
    // from your product portfolio.
    // Provide product data to the player using the methods below.
	

    player.updateProduct(productId, factory => factory
      .product(p => p
        .name('Super Nice T-Shirt')
        .sku('TSHIRT')
        .variations(v => [
          v()
          .imageUrls(['https://mycompany.com/images/super-nice-tshirt.jpg'])
          .name('White Super Nice T-Shirt')
          .sku('TSHIRT-WHITE')
          .sizes(s => [
            s()
            .name('One Size Fits All')
            .sku('TSHIRT-WHITE-ONESIZE')
            .price(pr => pr
              .current(29))
          ])
        ])
      )
    );
  });
});

TIP

For a comprehensive look at the product factory, see Updating product details

Examples

Providing product data

Example
A very basic example of a product with a single color and a single size. Currency and locale will default to the ones specified using the player.configure() method and in-stock status will always be true.

 player.on(player.EVENT.PROVIDE_PRODUCT_DATA, event => { 
   event.products.forEach(({ ref: sku, id: productId, url: publicUrl }) => { 
	 

     // Use the references provided above to fetch product details 
     // from your product portfolio. 
     // Provide product data to the player using the methods below.
		 

     player.updateProduct(productId, factory => factory 
       .product(p => p 
         .name('Super Nice T-Shirt') 
         .sku('TSHIRT') 
         .variations(v => [ 
           v() 
           .imageUrls(['https://mycompany.com/images/super-nice-tshirt.jpg']) 
           .name('White Super Nice T-Shirt') 
           .sku('TSHIRT-WHITE') 
           .sizes(s => [ 
             s() 
             .name('One Size Fits All') 
             .sku('TSHIRT-WHITE-ONESIZE') 
             .price(pr => pr 
               .current(29)) 
           ]) 
         ]) 
       ) 
     ); 
   }); 
 }); 

React to "Add to cart"

When a user clicks the "Add to cart" button inside the player, the player will emit a player.EVENT.ADD_TO_CART event. By configuring a listener for this event you can add items to your on-site cart accordingly.

Example

player.on(player.EVENT.ADD_TO_CART, (addedItem, callback) => { 
	

   yourAddToCartMethod(addedItem.sku) 
     .then(() => { 
       callback(true); // item successfully added to cart 
     }) 
     .catch(error => { 
       if (error.type === 'out-of-stock') { 
         // Unsuccessful due to 'out of stock' 
         callback({ 
           success: false, 
           reason: 'out-of-stock', 
         }); 
       } else { 
         // Unsuccessful due to other problems 
         callback(false); 
       } 
     }); 
 }); 
	

Updating the cart

In addition to adding items to the cart, a user can also choose to increase or decrease the quantity of a previously added item, or even remove the item from the cart. This is all handled by the player.EVENT.UPDATE_ITEM_IN_CART event.

Example 1: Data and methods available on the event

player.on(player.EVENT.UPDATE_ITEM_IN_CART, (updatedItem, callback) => { 

   // updatedItem.sku contains your reference to the product 

   // updatedItem.quantity 
   // number of products with above sku **currently** in the player cart 
	
   // updatedItem.previousQuantity 
   // number of products with above sku **previously** in the player cart 

   // updatedItem.callback() 
   // tells the player if the "update cart" was successful or not 
      
	 })

Example 2: Example implementation

CAUTION

Many e-commerce sites require a manual update of the user interface when the cart changes.

// The user wants to change the quantity of an item in cart 
 player.on(player.EVENT.UPDATE_ITEM_IN_CART, (updatedItem, callback) => { 

   if (updatedItem.quantity > 0) { 
     yourMethodToUpdateCart({ 
       sku: updatedItem.sku, 
       quantity: updatedItem.quantity, 
     }) 
     .then(() => { 
       // cart update was successful 
       callback(true); 
     }) 
     .catch(function(error) { 
       if (error.type === 'out-of-stock') { 
         callback({ 
           success: false, 
           reason: 'out-of-stock', 
         }); 
       } else { 
         callback(false); 
       } 
     }); 
   } 

   // user wants to remove the product from the cart 
   if (updatedItem.quantity === 0) { 
     yourMethodToDeleteItemFromCart(updatedItem.sku) 
       .then(() => { 
         // successfully deleted item 
         callback(true); 
       }) 
       .catch(() => { 
         // failed to delete item 
         callback(false); 
       }); 
   } 
 })

Customizing error messages:

Sometimes you might want to customize your own error messages. You can do this by passing the below object inside callback parameters:

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

Sync the player's internal cart

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: [],
    });
  }
});

Checkout

The player.EVENT.CHECKOUT event is triggered when the user clicks on the checkout button in the player. This is where you want to open your checkout page.

Example

player.on(player.EVENT.CHECKOUT, () => {
	
  // Use the showCheckout() method to safely
  // navigate the user to your checkout page
  player.showCheckout(window.location.origin + '/checkout');
	
});

Enabling the Miniplayer (floating player)

CAUTION

Miniplayer is not compatible with all websites. Read more about mini-player compatibility here‍.

To enable this feature you need to configure the behavior of certain buttons in the player.

Example

player.configure({
  buttons: {
    // Minimizes the player when viewer clicks on Checkout button
    checkout: player.BUTTON.MINIMIZE,
	
    // Minimizes the player when viewer clicks on a product
    product: player.BUTTON.MINIMIZE,
        
    // Replaces the close button with minimize button
    dismiss: player.BUTTON.MINIMIZE,
  }
});

Overriding product URLs (for cross-market shows)

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.

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) 
       ) 
     ); 
   }), 
);

Updating Product Details

Player Metrics‍