Kookeebeta
Retour au blog

Ajoutez un assistant IA à n’importe quel site avec une seule ligne de code

Help CenterDenis Povarov

Jusqu’ici, le widget de chat de Kookee avait un prérequis que personne n’avait demandé : React.

Si vous utilisez déjà React, aucun souci. Mais si votre site vitrine tourne sous WordPress, votre boutique sous Shopify, votre documentation sur un générateur de site statique, ou votre application sous Vue ou Angular, c’était rédhibitoire. Le widget répondait aux questions à partir de vos articles d’aide, et le seul moyen de l’obtenir était d’utiliser le bon framework.

Ce prérequis a disparu. Le widget de chat est désormais livré sous forme d’une simple balise script.

Une ligne

HTML 
<script async src="https://kookee.dev/chat/latest.js" data-api-key="YOUR_API_KEY"></script>

Collez-la avant </body>, et vous avez un assistant flottant qui répond à partir des articles publiés de votre centre d’aide. Pas de npm install, pas d’étape de build, pas de configuration de bundler, pas de framework.

Deux points à régler pour que ça fonctionne :

  1. Le vrai extrait de code, avec votre clé déjà dedans, se trouve dans le tableau de bord, sur la page Widget du site de votre projet. Copiez-le depuis cette page plutôt que de taper l’URL à la main.

  2. Ajoutez le domaine de votre site aux Origines autorisées du projet. Dès que la liste contient un domaine, les requêtes venues d’ailleurs sont rejetées. C’est ce qui empêche quelqu’un de récupérer votre clé dans le code source de la page pour faire tourner votre assistant sur son propre site.

Un domaine absent de cette liste est la cause la plus fréquente d’une bulle qui s’affiche alors que chaque question échoue. Si les réponses n’arrivent jamais, vérifiez d’abord la liste des origines.

Ce à quoi il répond

Le widget s’appuie sur vos articles d’aide publiés. Il y cherche à la fois par le sens et par mots-clés, répond en langage naturel et cite les articles utilisés, pour que le lecteur puisse ouvrir la source.

C’est plus important qu’il n’y paraît. Un assistant qui répond à partir de votre documentation reste dans les limites de votre documentation : il dit aux utilisateurs ce que vous avez réellement écrit. Et quand il ne sait pas répondre, vous apprenez précisément ce qui manque, au lieu de voir un modèle généraliste inventer une fonctionnalité que vous ne proposez pas.

L’adapter à votre site

Tout l’aspect visuel passe par des attributs data, si bien qu’une personne qui ne développe pas peut ajuster le widget en modifiant une seule ligne du template de la page :

HTML 
<script
  async
  src="https://kookee.dev/chat/latest.js"
  data-api-key="YOUR_API_KEY"
  data-title="Support"
  data-greeting="Bonjour ! Posez-moi n’importe quelle question sur le produit."
  data-placeholder="Saisissez votre question…"
  data-launcher-label="Besoin d’aide ?"
  data-position="bottom-left"
  data-theme="auto"
  data-primary-color="#ff6b00"
></script>

data-position accepte bottom-right ou bottom-left, data-theme accepte light, dark ou auto, et data-locale choisit la langue. data-base-url sert à faire pointer le widget vers un autre hôte d’API.

Le widget s’affiche dans un shadow root, et c’est grâce à lui que vous pouvez le coller sans risque dans un site que vous n’avez pas construit. Le CSS de votre page ne peut pas s’infiltrer et changer le style du chat, et le CSS du chat ne peut pas déborder et casser votre mise en page. Un thème Shopify aux sélecteurs globaux agressifs n’y touchera pas.

L’API JS, quand les attributs ne suffisent plus

Les attributs couvrent le cas courant. Pour brancher l’assistant sur votre propre interface, il y a window.KookeeChat :

JavaScript 
KookeeChat.open();
KookeeChat.close();
KookeeChat.toggle();
KookeeChat.sendMessage('Comment réinitialiser mon mot de passe ?');
KookeeChat.clearMessages();

Votre lien « Contacter le support » peut ainsi ouvrir l’assistant au lieu d’un client mail :

JavaScript 
document.querySelector('#support-link').addEventListener('click', (event) => {
  event.preventDefault();
  KookeeChat.open();
});

Les événements sont des abonnements, et chacun renvoie sa propre fonction de désabonnement :

JavaScript 
const unsubscribe = KookeeChat.on('sourceClick', (source) => {
  analytics.track('help_article_opened', { slug: source.slug });
});

on() accepte aussi open et close. Et si vous voulez contrôler toute la configuration au lieu de passer par les attributs, appelez init() vous-même. Il accepte tout ce que les attributs acceptent, plus quelques options qu’ils ne peuvent pas exprimer :

JavaScript 
KookeeChat.init({
  apiKey: 'YOUR_API_KEY',
  greeting: 'En quoi puis-je vous aider ?',
  suggestions: ['Comment démarrer ?', 'Quelles sont les offres ?', 'Comment résilier ?'],
  hideLauncher: true,
  zIndex: 9999,
  offset: { x: 24, y: 96 },
  onSourceClick: (source) => window.open(`/help/${source.slug}`, '_blank'),
  onOpenChange: (isOpen) => console.log('chat open:', isOpen),
});

suggestions vaut la peine d’être renseigné. Avec des questions de départ, l’utilisateur tape quelque chose. Sans elles, il fixe un champ vide et finit par se dire qu’il vous enverra plutôt un e-mail. hideLauncher masque la bulle par défaut pour que vous ouvriez le widget depuis votre propre bouton, et destroy() démonte le tout : utile dans une application monopage, quand l’utilisateur se connecte à un espace où l’assistant n’a pas sa place.

Les typages TypeScript se trouvent à l’adresse https://kookee.dev/chat/latest.d.ts.

Les détails qui comptent à l’usage

La conversation survit à la navigation entre les pages d’un même onglet : quelqu’un qui pose une question sur votre page de tarifs, puis passe à la page des fonctionnalités, ne perd pas le fil. Réduire le widget garde aussi la conversation, et seul le bouton Nouveau chat l’efface. Un mode agrandi sur toute la hauteur accueille les réponses longues, et les utilisateurs qui préfèrent ne voir que la bulle peuvent fermer l’étiquette du lanceur.

Aucun de ces comportements n’est un réglage auquel vous devez penser. C’est grâce à eux que le widget ne ressemble pas à une iframe plaquée sur la page.

Si vous utilisez déjà React

Rien ne change :

tsx 
import { KookeeChatWidget } from '@kookee/react/chat';

Ce composant reste le bon choix dans une application React : il vit dans votre arbre de composants et prend des props comme n’importe quel autre. La balise script ne le remplace pas. Elle s’adresse au groupe bien plus large des sites qui n’auraient jamais installé un paquet React pour obtenir une bulle de chat, et qui n’ont désormais plus à le faire.