Player API

BeLivePlayerWidget

`initialize`

initialize(option: PlayerWidgetOption): PlayerWidget

Initialize the widget and return the PlayerWidget instance

Parameters

option: PlayerWidgetOption

Returns PlayerWidget

`PlayerEventType`

An enumeration describing general events sent from the Player. To listen to events, use player.on().

`.READY`

Callback when player GUI is ready for any interactions

`.CLOSE`

Callback when users closed the player

`.NAVIGATE`

Callback when users navigate to a specific product url

`.MINIMIZED`

Callback when player is minimized

`.UNMINIMIZED`

Callback when player is uniminimized

`.SYNC_PRODUCT_DATA`

The 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().

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

`.UPDATE_ITEM_IN_CART`

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

`.SYNC_CART_STATE`

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

`.CHECKOUT`

The user pressed the checkout button from the player cart view.

`.AUTHENTICATION`

Callback when guest users click on chat input or send button

NOTE

The Admin need to switch off the Allow guest to chat settings when creating show

You can read more about how to Not allow guest to chat here

`.SHOW_PRODUCT_VIEW`

Callback when users click on product and product button is configured as BeLivePlayerWidget.Button.NONE

`.SHOW_SHARE_VIEW`

Callback when users click on share button and hideShareView is set to true in PlayerWidgetOption

`NavigationMode`

An enumeration describing how users should be navigated This will use to to specify the navigationMode in PlayerWidgetOption

`.IFRAME`

reload the overlay iframe (merchant website)

`Button`

Used to dictate the functionality of certain buttons inside the player.
To customize buttons behave in the player use buttons in PlayerWidgetOption
It includes the below behavior options:

`.MINIMIZE`

Minimize the player and act accordingly for minimized context.

`.CLOSE`

Close the player overlay.

`.LINK`

The button should behave like a link, relative to the current context. Opens the product URL/ checkout URL in a new browser tab.

`.NONE`

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

Usage example:

BeLivePlayerWidget.initialize({
   buttons: {
     // Set dismiss button behavior using a constant
     dismiss: BeLivePlayerWidget.Button.CLOSE,
   },
})

PlayerWidget methods

`open()`

open(showId?: string): PlayerWidget

Open the player widget

Parameters

showId: string A unique ID of the live show that was created from LORA Dashboard Defaults to PlayerWidgetOption.showId

Returns PlayerWidget

`setUser(userCredential)`

setUser(user: UserCredential): PlayerWidget

Set user credential

Parameters

user: UserCredential

Returns PlayerWidget

`minimize()`

minimize(): void

Minimizes the player

Returns void

`unminimize()`

unminimize(): void

Maximizes the player when it's minimized

Returns void

`close()`

close(): void

Close the player widget

Returns void

`on(eventName,callback)`

on<K>(name: K, fn: (payload: PlayerEventMap[K]) => void): PlayerWidget

Adds an event listener to the player. PlayerEventMap is a computed type which maps event names to their payloads.

Parameters

name: K The name of the event. Available events include PlayerEventType events.
fn: (payload: PlayerEventMap[K]) => void The handler function.

Returns PlayerWidget

`off(eventName,callback)`

off<K>(name: K, fn: (payload: PlayerEventMap[K]) => void): PlayerWidget

Removes an event listener from the player. PlayerEventMap is a computed type which maps event names to their payloads.

Parameters

name: K The name of the event. Available events include PlayerEventType events.
fn: (payload: PlayerEventMap[K]) => void The handler function.

Returns PlayerWidget

`removeAllListeners()`

removeAllListeners(): void

Removes all event listeners defined by PlayerWidget.on

Returns void

`showCheckout(url)`

showCheckout(url: string): void

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: BeLivePlayerWidget.Button.MINIMIZE
Minimizes the player and opens the link on the same window
checkout: BeLivePlayerWidget.Button.LINK
Opens the link in a new tab

Returns void

Usage example:

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

`updateCart(cartData)`

updateCart(cartData: CartItem[]): void

Update the player cart state.

Parameters

cartData: CartItem[]
An array of cart item

Returns void

Usage example:

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

`updateProduct(productId, productDetail)`

updateProduct(productId: string, productDetail: Product): void

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

Parameters

productId: string
The LORA generated ID for each product of a show. Found in the SYNC_PRODUCT_DATA event payload.
productDetail: ProductDetail
Product details that allow the player to properly display a product

Returns void

Usage example:

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

Interfaces

`PlayerWidgetOption`

Player configuration options

type PlayerWidgetOption = {
   showId?: string;
   triggerElement?: HTMLElement;
   navigationMode?: NavigationMode;
   buttons?: {
      dismiss?: Button;
      checkout?: Button;
   };
   ui?: {
      hideShareView?: boolean;
   };
};

Properties	Description	Type
showId	A unique ID of the live show that was created from LORA Dashboard.	String
triggerElement	An element that opens the player on click event	HTMLElement
navigationMode	The navigation behaviour when the user clicks on a product link. Defaults to BeLivePlayerWidget.NavigationMode.IFRAME	NavigationMode
buttons	Configures how buttons behave in the player. Reference: BeLivePlayerWidget.Button, `showCheckout()`	Object
ui	Hide UI elements when necessary. All hidable elements are listed below: `hideShareView`	Object

`ProductDetail`

Product details that allow the player to properly display a product

type Product = {
   name?: string;
   sku: string;
   brand?: string;
   shortDescription?: string;
   description?: string;
   defaultVariantIndex: number;
   colors?: ProductColor[];
};

Properties	Description	Type
name	Name of the product.	String
sku	sku (or any other identifier for your product) NOTE: Should be the same as your product reference defined in LORA Dashboard)	String
brand	(Optional) Brand name to display for the product	String
shortDescription	(Optional) Short product introductory text	String
description	(Optional) Description for the product	String
defaultVariantIndex	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	Number
colors	List of colors for the variations	ProductColor[]

`ProductColor`

type ProductColor = {
   sku?: string;
   colorName?: string;
   colorHexCode?: string;
   images?: string[];
   sizes?: ProductSize[];
};

Properties	Description	Type
sku	sku (or any other identifier for your product) specific down to this variation	String
colorName	Color name in the variation dropdown selector	String
colorHexCode	(Optional) Color Hex code e.g. '#db0b5b'	String
images	List of image urls for the variation ordered the same as you want it displayed	String[]
sizes	List of sizes for the variations	ProductSize[]

`ProductSize`

type ProductSize = {
   sku?: string;
   name?: string;
   currentPrice?: number;
   originalPrice?: number;
};

Properties	Description	Type
sku	sku (or any other identifier for your product) specific down to this size (used for add-to-cart)	String
name	Name of the size (used in dropdowns)	String
currentPrice	current price as a number	Number
originalPrice	(Optional) original price. Used in case the current is a sale price	Number

`UserCredential`

User information that will use for tracking purposes and displaying in live chat

type UserCredential = {
   id?: string;
   displayName?: string;
   email?: string;
   phone?: string;
};

Properties	Description	Type
id	A unique ID of a user that will use for tracking purposes	String
displayName	User display name that will use for tracking purposes and displaying in live chat	String
email	User email that will be used for authorisation or analytics purposes	String
phone	User phone that will be used for authorisation or analytics purposes	String

Player API

BeLivePlayerWidget​

initialize​

PlayerEventType​

.READY​

.CLOSE​

.NAVIGATE​

.MINIMIZED​

.UNMINIMIZED​

.SYNC_PRODUCT_DATA​

.ADD_TO_CART​

.UPDATE_ITEM_IN_CART​

.SYNC_CART_STATE​

.CHECKOUT​

.AUTHENTICATION​

.SHOW_PRODUCT_VIEW​

.SHOW_SHARE_VIEW​

NavigationMode​

.IFRAME​

Button​

.MINIMIZE​

.CLOSE​

.LINK​

.NONE​

PlayerWidget methods​

open()​

setUser(userCredential)​

minimize()​

unminimize()​

close()​

on(eventName,callback)​

off(eventName,callback)​

removeAllListeners()​

showCheckout(url)​

updateCart(cartData)​

updateProduct(productId, productDetail)​

Interfaces​

PlayerWidgetOption​

ProductDetail​

ProductColor​

ProductSize​

UserCredential​

BeLivePlayerWidget

`initialize`

`PlayerEventType`

`.READY`

`.CLOSE`

`.NAVIGATE`

`.MINIMIZED`

`.UNMINIMIZED`

`.SYNC_PRODUCT_DATA`

`.ADD_TO_CART`

`.UPDATE_ITEM_IN_CART`

`.SYNC_CART_STATE`

`.CHECKOUT`

`.AUTHENTICATION`

`.SHOW_PRODUCT_VIEW`

`.SHOW_SHARE_VIEW`

`NavigationMode`

`.IFRAME`

`Button`

`.MINIMIZE`

`.CLOSE`

`.LINK`

`.NONE`

PlayerWidget methods

`open()`

`setUser(userCredential)`

`minimize()`

`unminimize()`

`close()`

`on(eventName,callback)`

`off(eventName,callback)`

`removeAllListeners()`

`showCheckout(url)`

`updateCart(cartData)`

`updateProduct(productId, productDetail)`

Interfaces

`PlayerWidgetOption`

`ProductDetail`

`ProductColor`

`ProductSize`

`UserCredential`