Widget et SDK JavaScript

Une balise de script sur votre site. L'apparence se règle dans le Studio et s'applique en direct ; ce que l'agent a le droit de faire est épinglé à une version.

Le widget est un composant web servi par votre propre instance, sous /widget/widget.js. Il s'affiche selon le design que vous définissez pour l'agent, des couleurs et de la forme aux textes, au lanceur et aux zones. Un design enregistré s'applique aussitôt, sans republier l'agent.

<script src="https://rikoo.example.com/widget/widget.js"
        data-rikoo-token="rk_wgt_..." defer></script>

Le Studio vous donne ce snippet sur la fiche de l'agent : onglet Deploy, Configurer le widget, puis la section Mise en service. Le jeton public en est le seul attribut. Il désigne le déploiement, et le déploiement porte l'agent, l'environnement et la version épinglée. Le widget s'adresse à l'instance qui a servi le script.

Le comportement est gelé, la présentation est en direct

Les deux changent à des moments différents, à dessein. Un changement de couleur n'exige pas de nouvelle version d'agent. Un changement de ce que l'agent a le droit de faire n'atteint jamais un visiteur sans nouvelle version.

Le piloter depuis votre page

Au-delà d'une balise de script, le SDK du paquet @rikoo/widget vous donne le widget sous forme d'objet. Vous pouvez l'ouvrir dans un mode d'affichage (compact, sidebar, fullScreen, modal), le fermer, le masquer, démarrer une nouvelle conversation, déclarer l'écran où se trouve le visiteur avec setContext, et vous abonner à ses événements (open, close, conversation-started, turn-completed).

app.js

import rikoo from '@rikoo/widget';

const widget = rikoo.init({
  token: 'rk_wgt_...',
  appUrl: 'https://rikoo.example.com',
});

await widget.open.sidebar();
await widget.newConversation();

Les appels d'affichage renvoient une promesse résolue une fois que le widget a rendu l'état demandé. La balise de script expose le même objet sous window.rikoo, si bien qu'une page sans bundler peut aussi appeler rikoo.init. Chaque appel à init avec un autre jeton monte un widget de plus sur la page.

Savoir qui parle

Par défaut, un visiteur est anonyme et sa conversation appartient à son navigateur. Chaque déploiement a un mode d'identité du visiteur : anonymous (par défaut), verified ou required. Dans les deux derniers, votre backend signe une assertion de courte durée pour chaque utilisateur connecté, et le widget la présente avant chaque tour. Rikoo vérifie la signature avec la clé publique que vous avez enregistrée et rattache la conversation à cet utilisateur, sur tous ses appareils. En mode verified, un visiteur sans assertion valide continue en anonyme. En mode required, il est refusé.

Rikoo ne détient que la clé publique, et un visiteur ne peut pas se faire passer pour un autre en modifiant la page.

Travailler avec la page hôte

Le widget peut être autorisé à lire le champ que le visiteur désigne et à y écrire, à remplir un formulaire, à prendre une capture de la page, ou à observer les appels réseau de la page vers des origines que vous listez. Chaque capacité est désactivée par défaut et demande deux clés :

• L'exploitant l'active dans la configuration de l'agent (config.inPage). Elle est gelée avec la version de l'agent : la changer demande une nouvelle version.
• Le visiteur la déclenche par un geste : placer son curseur dans un champ, ou choisir l'entrée de capture puis envoyer l'image prévisualisée. Rien n'est lu avant ce geste.

L'observation du réseau n'a pas de geste du visiteur, parce que les données appartiennent au site. La liste d'origines la borne, et ce qui sort du navigateur se limite à la méthode, au statut, à l'origine et au chemin, à la durée et à la taille, jamais la query string ni les en-têtes. Un extrait borné et expurgé des corps n'est envoyé que si l'exploitant l'autorise en plus. Remplir un formulaire envoie sa structure (types, étiquettes, champs obligatoires, listes de choix), jamais ce que le visiteur a déjà saisi, et le widget ne le soumet jamais. Une écriture dans un champ se défait : le visiteur retrouve son texte en un clic.

Les origines autorisées sont contrôlées côté serveur

Un widget ne répond que pour les origines listées sur son déploiement. Copier la balise de script sur un autre domaine ne fonctionne pas : l'API contrôle l'en-tête Origin de chaque requête, pas le script.

Licence

Le widget, son SDK et les extensions de navigateur construites à partir de lui relèvent de la Rikoo Widget License, pas de l'AGPL-3.0 : intégrer le widget n'affecte jamais la licence de votre site. Il est gratuit pour toutes les éditions. Vous pouvez l'intégrer, et l'adapter à cette fin, sur les sites et applications que vous exploitez, pour que leurs visiteurs dialoguent avec une instance Rikoo. Vous ne pouvez pas le redistribuer comme œuvre autonome, le connecter à un autre backend, ni vous en servir pour bâtir un produit concurrent.