Products

The LiSA Player sends messages in response to various user interactions with products.

The player distinguishes different types of product interactions.

• Add to Cart

• Add to Wishlist

• Click

• Close Product List

• Emoji

• Emoji State Update

• Impression

• Open Product List

This message is sent by the LiSA Player to the host app / environment.

Properties

Along with all standard Message properties, a Product Interaction message includes the following additional properties:

Name	Type	Description
mediaItemId	string Required.	The mediaItemId property uniquely identifies the Media Item from which this message originates.
mediaItemType	MediaItemType Required.	The mediaItemType property specifies the type of Media Item from which this message originates. Refer to MediaItemType for detailed information.
messageType	Literal Required.	The messageType property specifies the distinct type of message.
productBrand	String Optional.	The productBrand property represents the localized name of the product's brand, if available.
productCurrency	String Optional.	The productCurrency property specifies the currency code (ISO 4217, 3-letter format) of the product price.
productId	String Required.	The productId property is the internal LiSA product identifier. This ID is unique within the LiSA system and is used for internal product tracking. Note: Do not confuse this with productReference, which may refer to an external or merchant-specific product identifier.
productOriginalPrice	Number Optional.	The productOriginalPrice property represents the original price of the product, if the product price is discounted.
productPrice	Number Optional.	The productPrice property represents the effective price of the product, which may be either the original price or the sale price, depending on availability.
productReference	String Optional.	The productReference property represents an external or merchant-specific identifier for the product. This ID is provided by the merchant or host system and may differ from the internal productId. It is used to reference the product in external systems, such as e-commerce platforms or inventory databases.
productTitle	String Required.	The productTitle property represents the localized name of the product.
progress	MediaProgress Required.	The progress property is an object that holds additional metadata related to the media playback progress of the current media item. Please refer to MediaProgress for detailed information.
variantId	String Optional.	The variantId property is the internal LiSA product variant identifier. This ID is unique within the LiSA system and is used for internal product variant tracking. Note: Do not confuse this with variantReference, which may refer to an external or merchant-specific product variant identifier.
variantReference	String Optional.	The variantReference property represents an external or merchant-specific identifier for the product variant. This ID is provided by the merchant or host system and may differ from the internal variantId. It is used to reference the product variant in external systems, such as e-commerce platforms or inventory databases.

Legacy Properties

If your integration uses LiSA Player Version 1, none of the properties described above will be available.

For LiSA Player Version 2, legacy properties can be ignored.

Name	Type	Description
action	String Required.	The distinct type of product interaction. ⚠️ Please use messageType instead.
additional	AdditionalProductData Required.	The additional property contains metadata related to product interactions. Please refer to AdditionalProductData for detailed information. ⚠️ Please use dedicated product-related properties instead.
first	Boolean Required.	The first property indicates, whether the message represents the first product interaction of a distinct type per product in the current visitor's session. ⚠️ This property is no longer supported in Player Version 2.
item	ProductItem Required.	The item property describes a limited set of product properties relevant to a specific product interaction. Please refer to ProductItem for detailed information. ⚠️ Please use dedicated product-related properties instead.
target	Literal Required.	The distinct target of product interaction. ⚠️ Please use messageType instead.

---

Type Definition

interface ProductMessage extends Omit<
  Message,
  'messageType' | 'sender'
> {
  mediaItemId: string;
  mediaItemType: MediaItemType;
  messageType:
    | 'lsc:product:add-to-cart'
    | 'lsc:product:add-to-wishlist'
    | 'lsc:product:click'
    | 'lsc:product:emoji'
    | 'lsc:product:impresssion';
  productBrand?: string;
  productCurrency?: string;
  productId: string;
  productOriginalPrice?: number;
  productPrice?: number;
  productReference?: string;
  productTitle: string;
  variantId?: string;
  variantReference?: string;
  progress: MediaProgress;
  sender: 'LiSA';
}

---

AdditionalProductData — Legacy

In addition to the standard Additional Data properties, the additional property contains metadata related to product interactions.

Name	Type	Description
action	String Optional.	The action property represents the action target of a carousel item interaction. Depending on the use-case it can either be a URL or a serialized JSON object, containing parameters required to execute upon the interaction in the host app / environment.
id	String Optional.	The id property represents the unique identifier of the product as specified in the customer's e-commerce system.
variantId	String Optional.	The variantId property represents the unique identifier of the selected product variant as specified in the customer's e-commerce system.

interface AdditionalProductData extends AdditionalData {
  action?: string;
  id?: string;
  variantId?: string;
}

ProductItem — Legacy

The ProductItem property describes a limited set of product properties relevant to a specific product interaction.

Name	Type	Description
data	ProductItemData Required.	The distinct type of product interaction. Please refer to ProductItemData for detailed information.
id	String Required.	The id property is the internal LiSA product identifier. This ID is unique within the LiSA system and is used for internal product tracking. Note: Do not confuse this with data.origin.id, which may refer to an external or merchant-specific product identifier.
type	Literal Required.	product

interface ProductItem {
  data: ProductItemData;
  id: string;
  type: 'product';
}

ProductItemData — Legacy

The ProductItemData object contains additional properties that are generally non-essential for most use cases.

• As these are legacy properties, we do not recommend using them.

• Instead, we encourage relying on the distinct properties available in the Product Interaction messages for better clarity and consistency.

Name	Type	Description
origin	ProductOrigin Optional.	The productOrigin property is an object that specifies essential details about the product's origin within the merchant's e-commerce system. Please refer to ProductOrigin for detailed information.

interface ProductItemData {
  origin?: ProductOrigin;
}

ProductOrigin — Legacy

Name	Type	Description
id	String Optional.	The id property represents an external or merchant-specific identifier for the product. This ID is provided by the merchant or host system and may differ from the LiSA-internal product identifier.

interface ProductOrigin {
  id?: string;
}