Widget de chat web

Intégrez un widget de chat propulsé par Cradle sur n'importe quel site avec une seule balise script — historique, indicateur de saisie et réponses temps réel.

Le widget web Cradle est un canal de chat complet, pas un formulaire de contact. Un visiteur voit un bouton flottant, ouvre une fenêtre de chat avec l'historique des messages, envoie un message, et reçoit une réponse de Cradle en temps réel.

Taille du bundle : ~49 KB gzippé.

Intégration

Ajoutez une balise script à n'importe quelle page :

<script
  src="https://cradle.example.com:31415/widget.js"
  data-cradle-widget
  data-api-key="wk_..."
  data-accent="#10b981"
  data-position="bottom-right"
  async></script>

Remplacez l'hôte et le port par ceux où votre endpoint Cradle widget est joignable. Pour des tests locaux, c'est http://localhost:31415/widget.js.

Attributs de configuration

Attribut	Requis	Description
`src`	oui	URL du bundle widget
`data-cradle-widget`	oui	Marqueur de montage
`data-api-key`	oui	Clé API widget depuis la config du canal
`data-accent`	non	Couleur hex pour le lanceur et le bouton d'envoi
`data-position`	non	`bottom-right` (défaut) ou `bottom-left`

Le thème, la position et la locale côté serveur sont renvoyés par GET /api/widget/config/:apiKey. Les attributs client remplacent certaines valeurs.

Architecture

packages/widget/ — bundle Vite IIFE, React inlined.
src/core/channels/widget-channel.ts — serveur Fastify dans le processus principal.
Le montage en shadow DOM isole les styles de la page hôte.
Pas de postMessage vers la fenêtre parente : toute la communication passe par HTTP et WebSocket vers Cradle.

Endpoints serveur

Endpoint	Objectif
`GET /widget.js`	Servir le bundle avec de longs en-têtes de cache
`GET /api/widget/config/:apiKey`	Thème, couleur, position, locale
`POST /api/widget/message`	Accepter un message visiteur (en-tête `X-Visitor-Id`)
`WS /api/widget/ws?visitorId=...&apiKey=...`	Réponses temps réel et événements de saisie

Comportement client

visitorId est généré à la première ouverture et stocké dans localStorage.
L'historique du chat est mis en cache localement, donc un rechargement de page conserve la conversation.
Le WebSocket se reconnecte automatiquement avec backoff exponentiel.
L'indicateur de saisie s'affiche pendant qu'une réponse est en attente.

Sécurité

La clé API widget est configurée par canal dans channels_config.widget.config.apiKey.
Une liste optionnelle allowedOrigins restreint les sites autorisés à charger le widget.
La limite de rate s'applique par IP + clé.
En production, exposez l'endpoint widget via un reverse proxy ou un tunnel et servez-le en HTTPS.