Widget V3

Le Widget V3 enregistre et lit les messages dans l’expérience utilisateur V3. Il fonctionne avec l’API v3.1 : votre serveur émet un jeton d’enregistrement ou de visualisation pour un mrid, et le widget reçoit ce jeton dans une propriété. Le même élément fonctionne selon quatre modes, choisis par son attribut mode.

Widget V3

L’élément

L’élément s’appelle livstick-widget-v3. Sa shadow root est ouverte. Définissez un autre nom de balise avec defineLivstickWidget("livstick-widget") si vous préférez le nom court. Le composant React accepte les mêmes props que les attributs et propriétés ci-dessous. Une variante pleine page, fullpage.html, lit sa configuration dans un template dont l’id est livstick-widget-v3-config. Les fichiers publiés sont assets/widget.v3.latest.js, widget.v3.module.js, widget.v3.css et integrity-manifest.json, sous le chemin widget-v3/ du CDN du widget.

Attributs

Les attributs sont reflétés depuis l’élément. Modifier un attribut redessine le widget. Ne mettez pas de jeton ni de clé d’édition dans un attribut : les attributs sont visibles dans le code source de la page et dans le DOM.

Nom	Type	Par défaut	Description
`mode`	`string`		Obligatoire. Le mode dans lequel le widget fonctionne. Toute autre valeur déclenche livstick:error avec le code invalid_config. Valeurs `record` `view` `gallery` `react`
`domain`	`string`		Obligatoire. Le domaine de la plateforme, résolu par l’appel d’initialisation (boot).
`api-url`	`URL`	`https://api.livstick.com`	L’URL de base de l’API utilisateur V3. Doit utiliser https ; http n’est accepté que pour localhost.
`app-url`	`URL`	`https://<domain>`	URL de base des liens d’invitation et de partage. Jamais déduite de l’adresse de la page courante.
`urid`	`string`		Code court du conteneur ou du message. Utilisé avec le mode record sans jeton d’enregistrement, et avec les modes view et gallery pour les pages publiques. Ignoré avec un jeton d’enregistrement.
`mrid`	`string`		Utilisé en mode view uniquement. Ignoré sans jeton de visualisation.
`gallery`	`string`	`offer`	Mode record uniquement. off n’affiche jamais d’étape d’invitation. offer demande si plusieurs personnes vont contribuer. forced affiche toujours l’étape d’invitation, pour un conteneur gallery. Valeurs `off` `offer` `forced`
`role`	`string`	`viewer`	Mode gallery. owner exige une propriété editKey. Valeurs `viewer` `owner`
`layout`	`string`	`mosaic`	Mode gallery. La disposition de la grille des messages. Valeurs `mosaic` `feed`
`lang`	`string`		Code de langue. Par défaut, la langue de l’appel d’initialisation.
`widget-key`	`string`		Clé du widget, envoyée dans l’en-tête X-Widget-Api-Key.
`style-url`	`URL`		Même signification que dans le widget V2.
`debug`	`boolean`	`false`	Même signification que dans le widget V2.
`fullscreen-desktop`	`boolean`	`false`	Même signification que dans le widget V2.
`instance-id`	`string`		Même signification que dans le widget V2.

Propriétés JavaScript

Les propriétés se définissent depuis un script ; elles ne sont jamais reflétées dans les attributs ni lues depuis l’URL. Chaque affectation redessine le widget. Le widget ne stocke rien : il ne conserve aucune valeur dans sessionStorage ni dans localStorage.

Nom	Type	Description
`editKey`	`string`	Mode record pour le premier message d’un conteneur (la clé d’édition renvoyée à la création). Mode gallery avec role owner, pour les outils d’invitation. Secret : définissez-la uniquement depuis un script.
`recordToken`	`string`	Mode record pour un mrid. Obtenu via POST /containers/{crid}/record-tokens. Son expiration est signalée par livstick:error avec le code token_expired ; demandez un nouveau jeton à votre serveur.
`viewToken`	`string`	Modes view et gallery. Obtenu via POST /containers/{crid}/view-tokens. Lecture seule : il ne permet ni réaction ni marque de visionnage.
`context`	`Record<mrid, { badge?, subtitle?, caption? }>`	Texte affiché à côté de chaque message en mode gallery, indexé par mrid. Lu uniquement quand la réponse de lecture contient des valeurs mrid, ce qui exige un jeton owner.
`config`	`{ prefill?, texts? }`	prefill : firstname, lastname et email, pour pré-remplir le formulaire d’enregistrement. texts : une table qui associe des clés de texte à des chaînes de remplacement.

Événements

Les événements remontent et traversent la frontière du shadow DOM (bubbles et composed valent tous deux true). Écoutez-les sur l’élément ou sur n’importe quel ancêtre.

Nom	Type	Description
`livstick:ready`	`{ mode, urid: string \| null }`	Le widget est prêt à afficher son premier écran.
`livstick:route-change`	`{ route, previousRoute }`	Le widget est passé à un autre écran. La route "invite" annonce l’étape d’invitation ; il n’existe pas d’événement distinct pour elle.
`livstick:recorded`	`{ urid, mrid, messageId, state, held, gallery }`	Un message a été envoyé. state vaut processing ou held ; held vaut true pour un message enregistré avec hold. gallery indique si le conteneur est une galerie. Valeurs `processing` `held`
`livstick:message-open`	`{ messageId, mrid, index, total }`	Un message a été ouvert dans un lecteur. mrid n’est renseigné que si le widget détient un jeton owner.
`livstick:reaction`	`{ messageId, kind, emoji }`	Une réaction a été envoyée. kind vaut quick, video ou thanks ; emoji est renseigné pour les réactions quick. Valeurs `quick` `video` `thanks`
`livstick:error`	`{ code, message, recoverable }`	Quelque chose a échoué. recoverable indique si l’utilisateur peut réessayer. Valeurs `invalid_config` `platform_unavailable` `capability_missing` `token_invalid` `token_expired` `not_found` `gallery_closed` `upload_failed` `media_permission_denied` `network`

Modes

Chaque mode a besoin de l’un des identifiants ci-dessous. Le mode est le seul réglage qui change : même élément, mêmes événements.

Nom	Type	Description
`record with editKey`	`capability`	Enregistre le premier message d’un conteneur. Le mode du conteneur détermine le parcours : un conteneur single saute l’étape d’invitation ; un conteneur gallery l’affiche, en deuxième et dernière étape. Avec gallery="offer", le formulaire demande si plusieurs personnes vont contribuer.
`record with recordToken`	`capability`	Enregistre un message pour le mrid du jeton. Un jeton avec hold à true garde le message retenu jusqu’à ce que votre serveur le libère : le widget indique au destinataire qu’il sera publié une fois le paiement confirmé.
`view`	`capability`	Lit un message, par urid ou par viewToken avec mrid. Les réactions ne sont disponibles qu’avec urid.
`gallery viewer`	`capability`	Affiche les messages d’une galerie, par urid ou par viewToken. Ouvre le lecteur en séquence.
`gallery owner`	`capability`	Affiche l’écran propriétaire d’une galerie : titre, nombre de messages, vignettes et outils d’invitation. Nécessite urid et editKey.
`react`	`capability`	Lit les messages en séquence avec les réactions, par urid. L’enregistrement de réponses et de remerciements fait partie de ce mode.

Règles du contexte

La propriété context ajoute un libellé à chaque message d’une galerie. Elle ne s’applique qu’en modes view et gallery, et seulement quand la réponse de lecture contient des valeurs mrid. Chaque champ est vérifié avant affichage.

Nom	Type	Description
`key`	`string`	Doit respecter le format du mrid : lettres, chiffres, deux-points, tiret bas et tiret, de 1 à 64 caractères. Les autres clés sont ignorées.
`badge`	`string`	16 caractères au plus.
`subtitle`	`string`	40 caractères au plus.
`caption`	`string`	140 caractères au plus. Les longueurs sont comptées en points de code.
`whole map`	`number`	1 000 entrées au plus. Une valeur qui n’est pas une chaîne est ignorée, et les caractères de contrôle sont supprimés. Le texte est affiché comme du texte, jamais comme du HTML, et n’est jamais envoyé à une API ni placé dans une URL.