Passer au contenu principal

:::note Versions distinctes Le SDK npm publié est 0.1.4. Le code source actuel du loader hébergé est widget.js v16 ; la version déployée peut différer et doit être vérifiée. :::

Intégrer avec un assistant de programmation IA

L’intégration recommandée côté application est le package npm @openstaticfish/chattybox. Le code de l’application peut configurer la clé publique et l’URL d’API, charger l’interface flottante gérée de ChattyBox depuis un layout navigateur persistant, ou utiliser le client headless pour créer une interface entièrement personnalisée.

Le script autonome widget.js est présenté en dernier comme solution de repli sans build pour les sites qui ne peuvent pas installer de packages npm.

Avant de commencer​

Terminez la configuration du chatbot avant de demander à un assistant de modifier votre application :

  • Vérifiez des réponses représentatives et leurs citations dans Tester le chatbot.
  • Dans Installer → Clés et domaines, vérifiez ou créez une clé publique de navigateur et contrôlez ses paramètres d’origine. Une clé préparée pour un site peut déjà être limitée à cette origine ; une clé sans restriction fonctionne depuis toutes les origines. Les restrictions sont un renforcement facultatif, pas une authentification des visiteurs.
  • Dans Installer → Installation sur le site web, sélectionnez une clé adaptée et copiez l’extrait. Utilisez son data-api-url s’il est présent ; sinon, obtenez le bon point de terminaison HTTP de l’API du widget dans la configuration de déploiement avant l’intégration.
  • Déterminez si un widget flottant persistant convient à l’application ou s’il vous faut une interface personnalisée avec positionnement et démontage propres aux routes.

La clé publique du widget et l’URL d’API sont destinées au navigateur, mais évitez tout de même de valider des valeurs propres à un environnement. Ne fournissez jamais de jeton de déploiement de configuration (qui est privé), d’identifiant administrateur ni de fichier d’environnement sans rapport.

Recommandé : monter l’interface gérée depuis npm​

Voici le prompt par défaut pour React, Next.js, Vite et les autres applications navigateur utilisant des packages.

Invite
Intégrer le package npm ChattyBox

Intègre ChattyBox à cette application à l’aide du package npm @openstaticfish/chattybox.

Configuration publique du navigateur :
- Clé d’API : [PASTE PUBLIC WIDGET KEY]
- URL d’API : [PASTE WIDGET API URL]

Commence par examiner le framework, le modèle de routage, le gestionnaire de packages, les conventions de variables d’environnement et le layout persistant de l’application. Indique-moi les fichiers que tu prévois de modifier avant d’éditer. Demande-moi des précisions si les routes où ChattyBox doit apparaître ne sont pas claires.

Exigences :
1. Installe @openstaticfish/chattybox avec le gestionnaire de packages déjà utilisé par ce dépôt.
2. Stocke la clé d’API publique et l’URL d’API en respectant la convention du framework pour les variables d’environnement exposées au navigateur. Ajoute des noms de remplacement à un fichier d’environnement d’exemple, mais ne valide pas de vraies valeurs.
3. Importe Chattybox depuis @openstaticfish/chattybox et crée un client avec apiKey et baseUrl.
4. Appelle client.mountWidget() uniquement dans le navigateur, après l’existence de document.body, depuis un shell persistant de l’application. Le widget flottant est ajouté sous document.body, pas à l’intérieur du composant.
5. Conserve le loader pendant les navigations SPA autorisées. Le SDK `0.1.4` compte les références uniquement pour des options de montage identiques ; appelle `remove()` sur chaque handle retourné lors d’un démontage volontaire. Dans le code source actuel du loader hébergé v16, le dernier handle déclenche le démontage de l’interface et des styles associés, et annule l’initialisation en attente, les nouvelles tentatives et le chat en cours ; `window.ChattyBox.destroy()` est l’équivalent côté loader hébergé. Vérifie les changements de route et de consentement : ne charge pas le widget avant le consentement requis ni sur les routes sensibles ou privées ; démonte-le en cas d’exclusion ou de retrait du consentement. Vérifie que le loader déployé prend en charge le démontage : masquer l’interface ou supprimer uniquement la balise script ne suffit pas. Le nettoyage ne peut pas annuler une requête déjà traitée par le serveur.
6. N’injecte pas widget.js manuellement, ne crée pas de proxy backend et n’introduis pas de second loader. mountWidget rejette une clé, une URL d’API, une URL de script, une locale ou une option debug différente tant que tous les handles existants n’ont pas été supprimés ; il ne conserve jamais silencieusement les anciennes options.
7. Préserve la navigation, les limites de rendu, la localisation, Analytics, le consentement et les styles existants. L’option de locale du SDK respecte la politique de surcharge par script du projet ; le SDK `0.1.4` ne fournit ni API de mise à jour réactive de la locale ni promesse `ready`. Le code source actuel du widget hébergé v16 peut actualiser les libellés appartenant au produit lorsque la locale résolue change, dans le respect de la politique de locale du projet ; vérifie la version déployée du loader avant de compter sur ce comportement, car il est versionné séparément. Le code source actuel du loader hébergé v16 programme au plus 10 tentatives de chat dans une fenêtre de nouvelle tentative de 30 secondes ; ce n’est pas un délai maximal strict pour une requête en cours. Le `sendMessage()` headless ne réessaie pas automatiquement. Le SDK `0.1.4` valide `baseUrl` et encapsule les erreurs de lecture du corps de réponse.
8. Effectue la modification ciblée la plus réduite possible et ne la déploie pas.
9. Exécute le build, le lint, la vérification des types et les tests pertinents du dépôt.
10. Indique les fichiers modifiés, les variables d’environnement que je dois définir, l’emplacement de montage de l’interface et la manière de la tester sur le site déployé.

Le code suivant illustre un rappel de cycle de vie exécuté dans le navigateur ; ce n’est pas un appel au niveau supérieur compatible avec le rendu serveur. Invoquez-le uniquement après l’existence de document.body et conservez le handle pour les démontages volontaires :

import { Chattybox } from '@openstaticfish/chattybox';

const client = new Chattybox({
  apiKey: PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: PUBLIC_CHATTYBOX_API_URL,
});

function mountInBrowser() {
  return client.mountWidget();
}

// Conservez le handle pendant les navigations autorisées et pour tout démontage volontaire.

Créer une interface personnalisée​

Choisissez cette option si votre application doit gérer elle-même la liste des messages, la saisie, les états de chargement, les erreurs, les citations et le placement, plutôt que de monter l’interface gérée.

Invite
Créer une interface ChattyBox headless

Crée une interface de chatbot personnalisée avec le package npm @openstaticfish/chattybox et son client headless.

Configuration publique du navigateur :
- Clé d’API : [PASTE PUBLIC WIDGET KEY]
- URL d’API : [PASTE WIDGET API URL]

Commence par examiner le framework de l’application, le système de composants, les modèles d’état, les styles, les conventions d’accessibilité et la configuration des tests. Propose les limites des composants et les fichiers avant de modifier quoi que ce soit.

Exigences :
1. Installe @openstaticfish/chattybox avec le gestionnaire de packages existant du dépôt.
2. Configure un client Chattybox avec apiKey et baseUrl à l’aide de variables d’environnement exposées au navigateur ; ne valide pas de vraies valeurs.
3. Utilise sendMessage() et conserve conversationId dans un état propre au visiteur ou à sa session pour regrouper les messages ; réinitialise-le en cas de changement d’utilisateur ou de session. Ne le partage jamais entre des visiteurs sans lien entre eux. Le modèle reçoit jusqu’à 12 messages récents enregistrés, chacun tronqué à 2 000 caractères, et non la conversation complète ni une mémoire permanente. Une clé publique, des restrictions d’origine et les identifiants de conversation n’authentifient pas les visiteurs et ne protègent pas les conversations privées. Évite les informations sensibles : les messages peuvent être enregistrés et visibles par les propriétaires du projet. Effacer l’état local ne supprime pas les enregistrements du serveur.
4. Affiche les réponses sous forme de texte sûr ou de Markdown assaini, et les sources HTTP(S) sous forme de liens accessibles en conservant leur ordre. N’insère jamais de HTML brut non fiable ni de lien utilisant un schéma dangereux.
5. Implémente les états d’attente, vide, erreur et nouvelle tentative. Une réponse de repli peut ne pas avoir de sources ; il n’existe pas de champ général `wasAnswered`. Lorsque le backend fournit `providerError`, traite-le comme un champ facultatif et affine son type de manière sûre avant de l’utiliser ; affiche une erreur générique du fournisseur plutôt qu’une réponse normale et ne réessaie pas aveuglément une réponse terminée avec une clé d’idempotence. Le SDK publié `0.1.4` peut ne pas typer les champs de réponse de la source actuelle : tolère leur absence. Gère à la fois `ChattyboxError` et les erreurs réseau non encapsulées ; `code` est facultatif.
6. Rejette les messages vides ou dont la longueur après suppression des espaces en début et en fin dépasse 2 000 caractères, empêche les soumissions en double et assure une utilisation correcte du clavier et du lecteur d’écran. sendMessage() headless ne réessaie pas automatiquement : utilise une clé idempotencyKey unique par message logique et réutilise exactement la même entrée lors d’une nouvelle tentative ; ne réessaie pas aveuglément chaque réponse 409. Le SDK `0.1.4` ne réessaie getWidgetConfig() qu’une fois après une réponse HTTP 400 ; le code source actuel du loader hébergé v16 réessaie séparément les requêtes GET de démarrage.
7. Monte l’interface uniquement sur les routes ou dans le layout que j’indique.
8. Suis les composants et les styles existants au lieu d’ajouter un nouveau système de design.
9. Ne charge pas widget.js et n’appelle pas mountWidget().
10. Exécute le build, le lint, la vérification des types et les tests pertinents, puis indique les fichiers modifiés et un plan de vérification.

Notes sur les frameworks​

Ajoutez une phrase à l’assistant si nécessaire :

  • Next.js App Router : « Utilise un petit Client Component dans un layout persistant et appelle mountWidget() depuis un effet réservé au navigateur, pas pendant le rendu. »
  • React SPA : « Monte depuis le shell persistant. Si le composant possède le dernier handle du SDK 0.1.4, retourne remove() pour un démontage volontaire ; sinon, conserve le loader partagé pendant les changements de route autorisés. »
  • Docusaurus : « Initialise depuis src/theme/Root côté navigateur et conserve le loader pendant la navigation autorisée dans la documentation. Vérifie la version du loader hébergé déployé et son comportement de locale avant de compter sur les mises à jour de langue côté client ; les changements de configuration du tableau de bord nécessitent toujours une réinitialisation. »
  • Vue, Nuxt, Svelte ou autre framework : « Utilise le cycle de montage réservé au navigateur dans un layout persistant ; choisis une interface headless si un démontage correspondant est nécessaire. »

Examiner une intégration SDK existante​

Invite
Examiner mon intégration du SDK ChattyBox

Examine cette intégration ChattyBox sans la déployer ni modifier du code sans rapport.

Vérifie que :
1. @openstaticfish/chattybox est installé et importé au lieu de dupliquer son comportement.
2. Un seul client Chattybox reçoit la clé d’API publique et l’URL d’API prévues.
3. Les variables d’environnement du navigateur respectent les règles de nommage des variables publiques de ce framework sans exposer d’identifiants privés.
4. Le widget hébergé utilise un shell persistant ; remove() ne sert qu’au démontage volontaire de l’interface, à l’exclusion d’une route après une navigation SPA ou au retrait du consentement. Une interface personnalisée dispose d’un véritable nettoyage de composant.
5. La navigation côté client et les remontages en développement ne créent pas d’instances en double.
6. Les limites de rendu, la localisation, Analytics, le consentement, l’accessibilité et le layout existants restent intacts. Les restrictions d’origine sont facultatives et ne sont pas une authentification des visiteurs ; une clé restreinte exige une origine de requête autorisée, et fetch dans Node.js n’envoie pas automatiquement les en-têtes des navigateurs. Vérifie que les routes privées et le retrait du consentement démontent réellement un widget initialisé au lieu de simplement le masquer.
7. L’implémentation possède des tests appropriés et n’inclut aucun refactoring sans rapport.

Retourne les résultats par niveau de gravité avec les chemins de fichiers et les références de lignes. Propose uniquement les plus petites corrections sûres et donne-moi les commandes exactes de vérification.

Pas de npm ni d’étape de build ?​

Utilisez le guide d’installation de widget.js uniquement si le site ne peut pas utiliser le package npm, par exemple pour du HTML simple, un champ de code personnalisé dans un CMS ou Google Tag Manager.

Invite
Installer le script du widget de repli

Installe le widget ChattyBox hébergé sur ce site en utilisant le script exact généré dans la vue Installation sur le site web de mon ChattyBox :

[PASTE COMPLETE WIDGET SCRIPT]

Inspecte d’abord le site et identifie le point d’insertion le plus sûr sur les pages publiques. Charge le script inchangé exactement une fois, uniquement lorsque le consentement requis est présent ; exclus les routes privées, d’administration et de paiement. Lors des changements de route SPA ou du retrait du consentement, démonte volontairement tout widget initialisé avant d’entrer dans un état exclu, et ne le réinitialise que lorsque c’est autorisé. Vérifie la prise en charge du démontage par le loader déployé : masquer l’interface ou supprimer la balise script seule ne suffit pas, et le démontage ne peut pas annuler une requête déjà traitée. Préserve la CSP, n’expose pas d’identifiants privés, ne déploie pas la modification et indique l’emplacement modifié ainsi qu’un plan de test dans le navigateur.

Tester le résultat​

  1. Examinez le diff et confirmez qu’aucun identifiant réel n’a été validé.
  2. Exécutez le build, le lint, la vérification des types et les tests habituels du projet.
  3. Déployez via le processus normal de revue.
  4. Vérifiez les routes prévues dans une fenêtre de navigation privée, y compris la navigation côté client.
  5. Posez une question prise en charge, suivez une citation et testez le comportement de repli.
  6. Vérifiez l’affichage mobile, l’utilisation au clavier et la console du navigateur.

Poursuivez avec la référence du SDK et la checklist de lancement.