Cart Integration

How to integrate the Bambuser player with your shopping cart

If you choose to show product details inside the player you automatically opt-in to using the player's internal cart. When a user clicks the "Add to cart" button inside the player, the selected product will be added to the player's internal cart. At this point, you need to ensure that the user's intention is reflected in your own on-site cart.

To do this, you will need to handle required player events for this functionality:

  • PROVIDE_PRODUCT_DATA 
  • ADD_TO_CART 
  • UPDATE_ITEM_IN_CART
  • CHECKOUT 
  • SYNC CART STATE

You can see a real-time demo  

Requirements

  • Have available methods to fetch product object on your side
  • Have available methods to add to the cart 
  • Have available methods to update items in the cart
  • Have available methods to check your cart status

Implementation

All events below have to be wrapped inside onBambuserLiveShoppingReady()

    window.onBambuserLiveShoppingReady = player => {
      // player = Bambuser Player API
      // handle below events here
    };

player.EVENT.PROVIDE_PRODUCT_DATA

TRIGGER

When the viewer opens the player

When scraping product information in the Bambuser Dashboard, we only get the product's title, thumbnail, brand, and product reference. However, with the internal cart feature, you can hydrate this product with more information like product images, prices, variations (up to two variation options)

In order to do that, you will first have to write a method that fetches the product object on your side (usually done through Product Reference). Then you can hydrate products in the show with extra information. 

Once you have your own product data, let's for the example call it "yourProduct" you can use the chained methods on the product instance created above to convert it into a product we understand (see example below).

For a comprehensive look at the product factory, see Updating Product Details‍.

Example

player.on(player.EVENT.PROVIDE_PRODUCT_DATA, function(event) {
        event.products.forEach(({ref: sku, id, url }) => { 
               const { ref: sku, id: productId, url: publicUrl } = event.products[0];
 
               const yourProduct = await yourGetMethodForYourProduct(sku);  
               // Full Example          
               // All methods described here:
                player.updateProduct(productId, factory => factory

                 // currency to display price in
                 .currency(yourProduct.currency)

                 // locale that product is localized to
                 .locale(yourProduct.locale)

                // -> the product method contains a new chain
                //    these are methods specific to this actual product
                .product(p => p

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

                   // 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)

                   // localized description for the product
                   .description(yourProduct.description)

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

                   // sku (or any other identifier for your product)
                   // NOTE: Must be same as your product reference
                   // defined in Bambuser Dashboard
                   .sku(yourProduct.skuOrProductIdentifier)

                    // -> the variations method contains a new chain
                    //    returned array defines variants (e.g. colors) of your product
                    .variations(v => yourProduct.colors.map(variation =>
                     // v contains a factory returning a new instance of a variation
                     v()

                     // -> the attributes method contains a new chain
                     //    defines attributes for the variation
                     .attributes(a => a
                         // which name to display for the color,
                         // if multiple variations exist,
                         // in the dropdown
                               .colorName(variation.colorName)
                     )
                       // list of image urls for the variation
                       // ordered the same as you want it displayed
                       .imageUrls(variation.images)

                       // name of the variation
                       .name(variation.name)

                       // sku (or any other identifier for your product)
                       // specific down to this variation
                       // NOTE: Must be same as your product reference
                       //       defined in Bambuser Dashboard
                       .sku(`${yourProduct.skuOrProductIdentifier}-${variation.colorId}`)

                        // -> the sizes method contains a new chain
                        //    defines sizes for the variation
                        .sizes(s => variation.sizes.map(size =>
                          // s contains a factory returning a new instance of a variation
                         s()
                           // 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)
                            // -> the price method contains a new chain
                            //    defines price for the variation and size combo
                            .price(p => p
                              // currency to show price in
                              .currency(sizePrice.currency)

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

                             // original price (in case current is a sale price)
                             .original(sizePrice.original)
                           )
                           // sku (or any other identifier for your product)
                           // specific down to this size
                           // NOTE: Must be same as your product reference
                           //       defined in Bambuser Dashboard
                           .sku(`${yourProduct.skuOrProductIdentifier}-${variation.colorId}-${size.sizeId}`)
                       ))
                      ))
                   ));
                })
            })

player.EVENT.ADD_TO_CART

TRIGGER

Whenever a viewer clicks on Add to Cart button inside the player

In the player, the viewer will be able to add products to the player cart.

To handle that, you will have to first write a method that adds a product into your native cart and handle it inside player.EVENT.ADD_TO_CART.

When callback(true), the product will be added to the Bambuser cart.

When callback(false), an appropriate error message will appear in the player. You can also modify your own error messages.

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

What is inside addedItem?

Content Description Type
addedItem.sku contains your reference to the product integer

player.EVENT.UPDATE_ITEM_IN_CART

TRIGGER

- Whenever the viewer modifies quantity in the player cart

- Whenever the viewer adds a product to the cart that is already in the player cart

In addition to adding items to the cart, a viewer can also increase or decrease the quantity of a previously added item, or even remove the item from the cart.

To handle that, you will have to first write a method that updates the quantity in your native cart and handle it inside EVENT.UPDATE_ITEM_IN_CART.

When callback(true), the product will be added to the Bambuser cart.

When callback(false), an appropriate error message will appear in the player. You can also modify your own error messages.

What is inside updatedItem?

Content Description Type
updatedItem.sku contains your reference to the product integer
updatedItem.quantity number of products with above sku currently in the player cart integer
updatedItem.previousQuantity number of products with above sku previously in the player cart integer
updatedItem.callback() tells the player if the "update cart" was successful or not boolean

Example

// 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) {
    yourUpdateCartMethod({
      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);
      }
    });
  }
});

player.EVENT.CHECKOUT

TRIGGER

Whenever a viewer clicks the "Checkout" button inside the player cart

When the viewer is happy with their shopping cart, they can click the Checkout button inside the player cart.

To handle that, you should specify the location of your website cart inside EVENT.CHECKOUT.

Example

player.on(player.EVENT.CHECKOUT, () => {
    player.showCheckout(window.location.origin + "/cart");
})

player.EVENT.SYNC_CART_STATE

TRIGGER

Whenever the viewer navigates back to the player

Currently, the update cart 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: [],
    });
  }
});

FAQ

There are many possibilities that would lead to this behavior. We recommend checking for console errors when you initiate the player. Some most common reasons are:


Was this article helpful?