Stickers

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

The player distinguishes different types of stickers interactions.

• Click — The sticker was clicked by a user

• Expire — The sticker has expired

• Impression — The sticker becomes visible in a user's viewport

• Unlock — The sticker's activation timer is complete

• Update — Poll details have been updated

• Voucher Claim — The voucher code of a voucher sticker has been claimed by a user

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

Properties

Along with all standard Message properties, a Sticker 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.
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.
stickerActionTarget	StickerActionTarget Optional.	The stickerActionTarget property represents the (localized) action to be executed when a user interacts with a UI element. It can be an identifier, a structured JSON payload, or a URL that opens in a new tab. Refer to StickerActionTarget for detailed information.
stickerActivationTimerDurationInSec	number Required.	The stickerActivationTimerDurationInSec property defines the length of the activation timer in seconds. If no activation timer is set for the sticker, the value is 0.
stickerActivationTimerIsActive	boolean Required.	The stickerActivationTimerIsActive property indicates, whether the sticker's activation timer is currently running.
stickerActivationTimerIsCompleted	boolean Required.	The stickerActivationTimerIsCompleted property indicates, whether the sticker's activation timer is complete.
stickerActivationTimerStartedAt	string Required.	The stickerActivationTimerStartedAt property represents the timestamp when the activation timer of the sticker was started — represented in ISO 8601 format. If no activation timer is set for the sticker, the value stores the timestamp of when the sticker was published.
stickerDetails	StickerDetails Optional.	The stickerDetails property represents the corresponding details object containing relevant information. The structure of this object varies depending on the stickerType. Refer to StickerDetails for detailed information.
stickerExpiryTimerDurationInSec	number Required.	The stickerExpiryTimerDurationInSec property defines the length of the expiry timer in seconds. If no expiry timer is set for the sticker, the value is 0.
stickerExpiryTimerIsActive	boolean Required.	The stickerExpiryTimerIsActive property indicates, whether the sticker's expiry timer is currently running.
stickerExpiryTimerStartedAt	string Required.	The stickerExpiryTimerStartedAt property represents the timestamp when the expiry timer of the sticker was started — represented in ISO 8601 format. If no activation timer is set for the sticker, the value stores the timestamp of when the sticker was published.
stickerId	string Required.	The stickerId property represents the unique sticker identifier.
stickerIsExpired	boolean Required.	The stickerIsExpired property indicates, whether the sticker has expired.
stickerIsUnlocked	boolean Required.	The stickerIsUnlocked property indicates, whether the sticker is unlocked. Either when the activation timer is not set or has completed AND the sticker has not expired.
stickerType	Enum Required.	The stickerType property represents the type of sticker being used. Allowed Values: alert – Displays an informational or warning alert. poll – Represents a poll for collecting user votes. product – Showcases a product-related sticker. voucher – Represents a discount or promotional voucher sticker.

---

Type Definition

interface StickerMessage extends Omit<
  Message,
  'messageType' | 'sender'
> {
  mediaItemId: string;
  mediaItemType: MediaItemType;
  messageType:
    | 'lsc:sticker:click'
    | 'lsc:sticker:expire'
    | 'lsc:sticker:impression'
    | 'lsc:sticker:unlock'
    | 'lsc:sticker:update'
    | 'lsc:sticker:voucher:claim';
  progress: MediaProgress;
  stickerActionTarget?: StickerActionTarget;
  stickerActivationTimerDurationInSec: number;
  stickerActivationTimerIsActive: boolean;
  stickerActivationTimerIsCompleted: boolean;
  stickerActivationTimerStartedAt: string;
  stickerDetails: StickerDetails;
  stickerExpiryTimerDurationInSec: number;
  stickerExpiryTimerIsActive: boolean;
  stickerExpiryTimerStartedAt: string;
  stickerId: string;
  stickerIsExpired: boolean;
  stickerIsUnlocked: boolean;
  stickerType: 'alert' | 'poll' | 'product' | 'voucher';
  sender: 'LiSA';
}

StickerActionTarget

type StickerActionTarget =
  | Record<string, string>
  | Record<string, Record<string | unknown>>
  | string;

The Sticker Action supports three different use cases:

• Identifier (String) — Represents an action or event that the host app / environment can interpret and execute.

• Localized String (Object) — If the action target is a localized URL to be opened in a new tab, each key of the object represents a language code and the corresponding value contains the URL.

• Localized Structured Data (String) — For more complex action definitions the action target contains an object, where each key represents a language code and the corresponding value contains an object structure.

StickerDetails

The StickersDetails type defines the corresponding details for each sticker based on its type.

Alert

The Alert sticker does not contain any specific details, so the stickerDetails value is always an empty object.

Poll

The Poll sticker does not contain any specific details, so the stickerDetails value is always an empty object.

Product

The Product sticker specifies the essential product properties and CTA behavior:

---

ctaBehavior — {Enum} Optional. Indicates whether upon user interaction the product is added to card directly, or its PDP is opened. Default: view

---

productBrand — {string} Optional. The name of the product's brand.

---

productCurrency — {CurrencyCode} Optional. The currency code associated with the product price.

---

productId — {string} Represents 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. Represents the original price of the product, if the product price is discounted.

---

productPrice — {number} Optional. Represents the effective price of the product, which may be either the original price or the sale price, depending on availability.

---

productReference — {string} Optional. 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} Optional. Represents the localized name of the product.

---

variantId — {string} Optional. Represents 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. 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 platform

---

interface ProductStickerDetails {
  ctaBehavior?: 'add-to-cart' | 'view';
  productBrand?: string;
  productCurrency?: string;
  productId: string;
  productOriginalPrice?: number;
  productPrice?: number;
  productReference?: string;
  productTitle: string;
  variantId?: string;
  variantReference?: string;
}

Voucher

The Voucher sticker specifies the voucher code and redemption CTA behavior:

---

ctaBehavior — {Enum} Optional. Indicates whether upon user interaction the voucher code is added to card directly, or copied to clipboard. Default: clipboard

---

voucherCode — {string} Optional.

---

voucherDiscountType — {Enum} Optional. Indicates whether the voucher discount value is applied as a fixed value or percentage value.

---

voucherDiscountLabel — {string} Optional. Determines how the voucher discount should be rendered.

---

voucherDiscountValue — {number} Optional. The numeric discount value.

---

voucherExpiresAt — {string} Optional. The date, when the voucher code expires. Represented in form of an ISO 8601 timestamp.

---

interface VoucherStickerDetails {
  ctaBehavior?: 'add-to-cart' | 'clipboard';
  voucherCode?: string;
  voucherDiscountLabel?: string;
  voucherDiscountType?: 'fixed' | 'percentage';
  voucherDiscountValue?: number;
  voucherExpiresAt?: string;
}

---