Widget V3

Widget V3 records and plays messages in the V3 user experience. It works with the v3.1 API: your server mints a record token or a view token for one mrid, and the widget receives that token as a property. The same element runs in four modes, chosen by its mode attribute.

Widget V3

The element

The element is livstick-widget-v3. Its shadow root is open. Define a different tag name with defineLivstickWidget("livstick-widget") if you prefer the short name. The React component has the same props as the attributes and properties below. A full-page form, fullpage.html, reads its configuration from a template with the id livstick-widget-v3-config. The published files are assets/widget.v3.latest.js, widget.v3.module.js, widget.v3.css and integrity-manifest.json, under the widget-v3/ path of the widget CDN.

Attributes

Attributes are reflected from the element. Changing an attribute re-renders the widget. Do not put a token or an edit key in an attribute: attributes are visible in the page source and in the DOM.

Name	Type	Default	Description
`mode`	`string`		Required. The mode the widget runs in. Any other value raises livstick:error with code invalid_config. Values `record` `view` `gallery` `react`
`domain`	`string`		Required. The domain of the platform, resolved through the boot call.
`api-url`	`URL`	`https://api.livstick.com`	The user API V3 base URL. Must use https; http is accepted for localhost only.
`app-url`	`URL`	`https://<domain>`	Base URL of invitation and share links. Never taken from the current page location.
`urid`	`string`		Short code of the container or message. Used with the record mode without a record token, and with view and gallery modes for public pages. Ignored for a record token.
`mrid`	`string`		Used in view mode only. Ignored without a view token.
`gallery`	`string`	`offer`	Record mode only. off never shows an invitation step. offer asks whether several people will contribute. forced always shows the invitation step, for a gallery container. Values `off` `offer` `forced`
`role`	`string`	`viewer`	Gallery mode. owner requires an editKey property. Values `viewer` `owner`
`layout`	`string`	`mosaic`	Gallery mode. The arrangement of the message grid. Values `mosaic` `feed`
`lang`	`string`		Language code. Defaults to the language of the boot call.
`widget-key`	`string`		Widget key, sent in the X-Widget-Api-Key header.
`style-url`	`URL`		Same meaning as in the V2 widget.
`debug`	`boolean`	`false`	Same meaning as in the V2 widget.
`fullscreen-desktop`	`boolean`	`false`	Same meaning as in the V2 widget.
`instance-id`	`string`		Same meaning as in the V2 widget.

JavaScript properties

Properties are set from script, never reflected to attributes and never read from the URL. Each assignment re-renders the widget. The widget stores nothing: it keeps no value in sessionStorage or localStorage.

Name	Type	Description
`editKey`	`string`	Record mode for the first message of a container (the edit key returned on creation). Gallery mode with role owner, for the invitation tools. Secret: set it from script only.
`recordToken`	`string`	Record mode for one mrid. Obtained from POST /containers/{crid}/record-tokens. Its expiry is reported as livstick:error with code token_expired; ask your server for a new token.
`viewToken`	`string`	View and gallery modes. Obtained from POST /containers/{crid}/view-tokens. Read-only: it gives no reaction and no seen mark.
`context`	`Record<mrid, { badge?, subtitle?, caption? }>`	Text shown next to each message in gallery mode, keyed by mrid. Only read when the view response carries mrid values, which requires an owner token.
`config`	`{ prefill?, texts? }`	prefill: firstname, lastname and email, to pre-fill the record form. texts: a map of text keys to replacement strings.

Events

Events bubble and cross the shadow boundary (bubbles and composed are both true). Listen on the element or on any ancestor.

Name	Type	Description
`livstick:ready`	`{ mode, urid: string \| null }`	The widget is ready to show its first screen.
`livstick:route-change`	`{ route, previousRoute }`	The widget moved to another screen. The route "invite" is how the invitation step is announced; there is no separate event for it.
`livstick:recorded`	`{ urid, mrid, messageId, state, held, gallery }`	A message was sent. state is processing or held; held is true for a message recorded with hold. gallery tells whether the container is a gallery. Values `processing` `held`
`livstick:message-open`	`{ messageId, mrid, index, total }`	A message was opened in a player. mrid is set only when the widget holds an owner token.
`livstick:reaction`	`{ messageId, kind, emoji }`	A reaction was sent. kind is quick, video or thanks; emoji is set for quick reactions. Values `quick` `video` `thanks`
`livstick:error`	`{ code, message, recoverable }`	Something failed. recoverable tells whether the user can retry. Values `invalid_config` `platform_unavailable` `capability_missing` `token_invalid` `token_expired` `not_found` `gallery_closed` `upload_failed` `media_permission_denied` `network`

Modes

Each mode needs one of the credentials below. The mode is the only switch: the same element, with the same events.

Name	Type	Description
`record with editKey`	`capability`	Records the first message of a container. The container mode decides the flow: a single container skips the invitation step; a gallery container shows it, as step two of two. With gallery="offer", the form asks whether several people will contribute.
`record with recordToken`	`capability`	Records one message for the mrid of the token. A token with hold set to true keeps the message held until your server releases it: the widget tells the recipient that it is published when the payment is confirmed.
`view`	`capability`	Plays one message, by urid or by viewToken with mrid. Reactions are available with urid only.
`gallery viewer`	`capability`	Shows the messages of a gallery, by urid or by viewToken. Opens the player in sequence.
`gallery owner`	`capability`	Shows the owner screen for a gallery: title, count, thumbnails and the invitation tools. Needs urid and editKey.
`react`	`capability`	Plays messages in sequence with reactions, by urid. Reply recording and thank-you recording are part of this mode.

Context rules

The context property adds a label to each message of a gallery. It is applied only in view and gallery modes, and only when the view response carries mrid values. Each field is checked before display.

Name	Type	Description
`key`	`string`	Must match the mrid pattern: letters, digits, colon, underscore and hyphen, 1 to 64 characters. Other keys are ignored.
`badge`	`string`	16 characters at most.
`subtitle`	`string`	40 characters at most.
`caption`	`string`	140 characters at most. Lengths are counted in code points.
`whole map`	`number`	1,000 entries at most. A value that is not a string is ignored, and control characters are removed. The text is shown as text, never as HTML, and never sent to an API or put in a URL.