Cart integration

Shopping is love, shopping is life! To watch your favorite host and shop at the same time, it’s the best you can get in life!

To boost a seamless and complete live shopping experience for our LORA, we need to enable users that are watching the live shows to be able to purchase any featured products in the live show. This experience should include the entire shopping experience from choosing a product size, quantity, design, and price to adding to the shopping cart and checking out.

Requirements

Your e-commerce app/platform has available methods/API endpoint for:

• Fetching product details
• Adding products to the cart
• Updating items in the cart
• Checking your cart status (optional)

All events below have to be used after BeLivePlayerWidget.initilize

const player = BeLivePlayerWidget.initialize({
   showId: "SHOW_ID",
});
// Handle player events here
// See the examples below

Implementation

To make use of the player cart feature, you need to handle some cart-related events. You will find the list of required events and configurations with details and examples below.

Required events to be handled

• SYNC_PRODUCT_DATA
• ADD_TO_CART
• UPDATE_ITEM_IN_CART
• CHECKOUT
• SYNC_CART_STATE

Syncing more data to player products

Event name: BeLivePlayerWidget.PlayerEventType.SYNC_PRODUCT_DATA

TRIGGER

• When the viewer opens the player

When adding products in the LORA Dashboard, we only store the product's title, thumbnail, brand, and a product reference. However, to use the player cart feature, you need to hydrate this product with more product details such as:

• More product images
• Variations (color, size)
• Prices

In order to do that, you will first have to write a method that fetches the product details from your inventory. Then you can use a player API method called updateProduct(...) in order to hydrate products in the show with extra information.

Event payload

Property	Description	Type
products	Contains all show's products added through the LORA dashboard. Each product object includes: url : URL of the product ref : Product reference id : LORA generated ID for each product in the player. This id is passed as the first argument of the player.updateProduct() method	Array

Example code

player.on(BeLivePlayerWidget.PlayerEventType.SYNC_PRODUCT_DATA, (products) => {
   products.forEach(async ({ ref: sku, id: loraProductId }) => {
      const yourProduct = await yourGetProductMethod(sku);
      player.updateProduct(loraProductId, {
         name: yourProduct.name,
         brand: yourProduct.brand,
         shortDescription: yourProduct.shortDescription,
         description: yourProduct.description,
         defaultVariantIndex: 0,
         colors: yourProduct.colors.map(color => ({
               sku: color.sku,
               colorName: color.colorName,
               colorHexCode: color.colorHexCode,
               images: color.images,
               sizes: color.sizes.map(size => ({
                  name: size.name,
                  sku: size.sku,
                  currentPrice: size.currentPrice,
                  originalPrice: size.originalPrice,
               }))
         })),
      })
   })
})  

Find more details on Player API Reference.

---

Handle Add To Cart event

Event name: BeLivePlayerWidget.PlayerEventType.ADD_TO_CART

TRIGGER

• When 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 reflect this event to you native cart, you will need to use your own method to add the product to the cart in the PlayerEventType.ADD_TO_CART event handler.

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

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

Event payload

Property	Description	Type
addedItem.sku	Contains your reference to the product	String
callback	To inform the player cart if the process of handling the event was successful or unsuccessful	Function

Example code

player.on(BeLivePlayerWidget.PlayerEventType.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);
         }
      });
}); 

Customizing cart operations error

Sometimes you might want to customize your own error messages for ADD_TO_CART and UPDATE_ITEM_IN_CART callbacks. You can do this by passing the below object as the argument when invoking callback method:

Usage Example

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

Handle Update Cart event

Event name: BeLivePlayerWidget.PlayerEventType.UPDATE_ITEM_IN_CART

TRIGGER

• Whenever the viewer modifies quantity from 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 reflect this event to you native cart, you will need to use your own method to update the product to the native cart within the PlayerEventType.UPDATE_ITEM_IN_CART event handler.

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

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

Event payload

Property	Description	Type
updatedItem.sku	Contains your reference to the product	String
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
callback	To inform the player cart if the process of handling the event was successful or unsuccessful	Function

Example code

//The user wants to change the quantity of an item in cart
player.on(BeLivePlayerWidget.PlayerEventType.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);
         }
      });
   }
   // 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 cart operations error

Sometimes you might want to customize your own error messages for ADD_TO_CART and UPDATE_ITEM_IN_CART callbacks. You can do this by passing the below object as the argument when invoking callback method:

Usage Example

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

Handle Go to Checkout event

Event name: BeLivePlayerWidget.PlayerEventType.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 PlayerEventType.CHECKOUT.

Example code

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

Sync the player cart

Event name: BeLivePlayerWidget.PlayerEventType.SYNC_CART_STATE

TRIGGER

• Whenever the viewer navigates back to the player

Currently, the update cart does not support anything more than emptying the player cart.

Example code

player.on(BeLivePlayerWidget.PlayerEventType.SYNC_CART_STATE, () => {
   // Use your method to check cart state
   yourMethodToGetCartItems().then((yourCartItems) => {
      if (yourCartItems.length > 0) {
         player.updateCart(
            yourCartItems.map((yourCartItemData) => ({
               sku: yourCartItemData.sku,
               quantity: yourCartItemData.quantity,
               imageUrl: yourCartItemData.imageUrl,
               name: yourCartItemData.name,
               description: yourCartItemData.description,
               currentPrice: yourCartItemData.currentPrice,
               originalPrice: yourCartItemData.originalPrice,
               sizeName: yourCartItemData.sizeName,
               colorName: yourCartItemData.colorName,
            }))
         );
      } else {
         // Emptying the in-player cart
         player.updateCart([]);
      }
   });
});