Player API reference

Events

Listed below are all the events emitted by the LiSA player. Use .on() to register event listeners to each of these events.

library.player.Event.CART_VIEW

User clicks the shopping cart CTA.

Parameters:

url — The shopping cart URL.

Usage example:

player.on(player.Event.CART_VIEW, (url) => {
  // Open the shopping cart in the quick view component
  library.quickView.show(url);
});

library.player.Event.CLOSE

The player has been closed.

Usage example:

player.on(player.Event.CLOSE, () => {
  console.log('Player closed');
});

library.player.Event.ERROR

The player threw an error.

Parameters:

type — An error type indicator. message — The error message.

Usage example:

player.on(player.Event.ERROR, (type, message) => {
  console.log(`Error of type ${type} with message ${message}`);
});

library.player.Event.OPEN

The player has been opened.

Parameters:

showId — The identifier of the show that has been loaded.

Usage example:

player.on(player.Event.OPEN, (showId) => {
  console.log(`Show ${showId} is playing`);
});

library.player.Event.READY

LiSA player is ready for communication.

Usage example:

player.on(player.Event.READY, () => {
  player.joinUser({ id: 'f24f8c5f-e500-44db-a095-3781246100e9', name: 'John Doe' });
});

library.player.Event.PRODUCT_ADD_TO_CART

User adds a product to the shopping cart

Parameters:

data — An object providing the products identifier (id) and action. action can either be a product URL (to open its PDP) or a serialized JSON structure required for executing the desired event action. Type definition at the end of this document.

first — Indicator, whether it is the first time this event is triggered for the respective product.

product — The Product data.

Usage example:

player.on(player.Event.PRODUCT_ADD_TO_CART, (data, first, product) => {
  addToCart(product.origin.id);
});

library.player.Event.PRODUCT_GRANT_REACTION

User "likes" a product.

Parameters:

data — An object providing the products identifier (id) and action. action can either be a product URL (to open its PDP) or a serialized JSON structure required for executing the desired event action. Type definition at the end of this document.

first — Indicator, whether it is the first time this event is triggered for the respective product.

product — The Product data.

Usage example:

player.on(player.Event.PRODUCT_GRANT_REACTION, (data, first, product) => {
  addToWishList(product.origin.id);
});

library.player.Event.PRODUCT_REVOKE_REACTION

User "unlikes" a product.

Parameters:

data — An object providing the products identifier (id) and action. action can either be a product URL (to open its PDP) or a serialized JSON structure required for executing the desired event action. Type definition at the end of this document.

first — Indicator, whether it is the first time this event is triggered for the respective product.

product — The Product data.

Usage example:

player.on(player.Event.PRODUCT_REVOKE_REACTION, (data, first, product) => {
  removeFromWishList(product.origin.id);
});

library.player.Event.PRODUCT_VIEW

User clicks a product card to see its details.

Parameters:

data — An object providing the products identifier (id) and action. action can either be a product URL (to open its PDP) or a serialized JSON structure required for executing the desired event action. Type definition at the end of this document. first — Indicator, whether it is the first time this event is triggered for the respective product. product — The Product data.

Usage example:

player.on(player.Event.PRODUCT_VIEW, (data, first, product) => {
  // data action contains the product URL in this example
  library.quickView.show(data.action);
});

library.player.Event.SHOW_READY

The show has finished initialisation.

Parameters:

data — An object providing show related data and a map of products featured in the show. Type definition at the end of this document.

Usage example:

// Check, if any of the products that are featured in the show, is already
// on the user's wish list and invoke LiSA player's like product option.
player.on(player.Event.SHOW_READY, (data) => {
  Object.keys(data.products).forEach((id) => {
    if (wishListContains(id)) {
      player.grantLike(data.products[id]);
    }
  });
});

Methods

This section lists the public methods the LiSA player object exposes.

grantLike(input: CarouselItemInput)

Pre-fill the heart (or any other reaction icon) on a product carousel item. This can be useful, if you integrate the carousel item reaction feature with your wish list or favorites. LiSA does not store user data including product likes granted during a show. In order for you to reflect the current users wish list or favorites with the products featured in a show, grantLike helps pre-filling the reaction icon.

player.grantLike({
  id: '7df0f4f8-3b85-4b2c-80af-e6d7b1bf604a',
  type: 'product',
});

joinUser(input: UserJoinInput)

In case your storefront or website context provides access to profile data of authenticated users, you can pass a user's profile data to the LiSA player. This enables you to re-use the user's data for a more seamless user experience, e.g. displaying a user's avatar in the chat or using his name as chat handle. joinUser(input: UserJoinInput)

In case your storefront or website context provides access to profile data of authenticated users, you can pass a user's profile data to the LiSA player. This enables you to re-use the user's data for a more seamless user experience, e.g. displaying a user's avatar in the chat or using his name as chat handle.

player.joinUser({
  avatar: 'https://your-cdn.net/path/to/avatar.png',
  consent: true, // User must declare consent to chat disclaimer
  editable: false, // User may not edit their user name when joining the chat
  id: '7df0f4f8-3b85-4b2c-80af-e6d7b1bf604a',
  name: 'Jane Doe',
});

maximize()

When the LiSA player is minimized, invoke this method to maximize it again.

Usage example:

player.maximize();

minimize()

Minimizes the LiSA player.

Usage example:

player.minimize();

off(event: string, handler: () => void)

Removes a previously registered event listener from receiving any more events.

Parameters

event — A string which specifies the type of event for which to remove an event listener.

handler — The event listener function of the event handler to remove from the LiSA player.

The event listener function of the event handler must be the same as at the time of registration. Using .bind() changes the function reference.

Calling off() with arguments that do not identify any currently registered event listener on the LiSA player has no effect.

Usage example:

const handler = (err) => {
  console.error('Player threw error', err);
};

// Register the event handler
player.on(player.Event.ERROR, handler);

// Remove the event handler again
player.off(player.Event.ERROR, handler);

on(event: string, handler)

Registeres an event handler for any of the events listed above.

Usage example:

// Launch the quick view upon a product view event
player.on(player.Event.PRODUCT_VIEW, (payload, first, product) => {
  library.quickView.show(payload.action));
});

removeAllListeners(event: string)

Remove all event listeners previously registered to the LiSA player.

Usage example:

player.on(player.Event.CART_VIEW, (url) => console.log('View cart', url));

player.on(player.Event.OPEN, () => console.log('Player open'));

// Prevent all listeners from being invoked
player.removeAllListeners();

revokeLike(input: CarouselItemInput)

Oppsite of grantLike.

player.revokeLike({
  id: '7df0f4f8-3b85-4b2c-80af-e6d7b1bf604a',
  type: 'product',
});

Type definitions

Product event data

type ProductEventData = {
    /**
     * The value from a product's URL.
     * 
     * Depending on the implementation of processing LiSA product events, a
     * product's URL can either be a regular URL or a JSON object containing
     * implementation specific data.
     */
    action: Record<string,string> | string;
    /**
     * The original product id.
     */
    id: string;
    /**
     * The original product variant id, if available.
     */
    variantId?: string;
};

Show event data

type ShowEventData = {
    /**
     * A map of products featured in the show.
     * 
     * The key represents the original product ID, while value is the LiSA
     * internal product id.
     */
    products: { [key: string]: string };
    /**
     * The date of the current show in ISO 8601 format.
     * 
     * Example: "2022-09-20T07:50:00.000Z"
     */
    showDate?: string;
    /**
     * The ID of the current show.
     * 
     * Example: "23bd8b82-b89a-475d-bc56-6050a4ef9ca9"
     */
    showId?: string;
    /**
     * The state of the current show.
     * 
     * Example: "replay"
     */
    showState?: 'live' | 'postShow' | 'preShow' | 'replay';
    /**
     * The title of the current show.
     *
     * Since the title is a localized field, LiSA will use the viewers browser
     * locale or a language override (either by `language` or `store` query 
     * parameter) to determin the localized value.
     * 
     * Example: "Brushes Masterclass"
     */
    showTitle?: string;
    /**
     * The URL of the current show.
     * 
     * Example: "https://[client].loveslisa.tech/s/23bd8b82-b89a-475d-bc56-6050a4ef9ca9"
     */
    showUrl?: string;
};