# 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:** ```javascript 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:** ```javascript 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:** ```javascript 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:** ```javascript player.on(player.Event.OPEN, (showId) => { console.log(`Show ${showId} is playing`); }); ``` library.player.Event.READY LiSA player is ready for communication. **Usage example:** ```javascript 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:** ```javascript 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:** ```javascript 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:** ```javascript 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:** ```javascript 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:** ```javascript // 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. ```javascript 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. ```javascript 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:** ```javascript player.maximize(); ``` minimize() Minimizes the LiSA player. **Usage example:** ```javascript 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. {% hint style="warning" %} 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. {% endhint %} **Usage example:** ```javascript 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:** ```javascript 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. ```javascript player.revokeLike({ id: '7df0f4f8-3b85-4b2c-80af-e6d7b1bf604a', type: 'product', }); ``` ### Type definitions #### **Product event data** ```typescript 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; /** * The original product id. */ id: string; /** * The original product variant id, if available. */ variantId?: string; }; ``` #### Show event data ```typescript 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; }; ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.hello-lisa.com/developers/widgets/api-reference/player-api-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.