Contrôlez le widget depuis votre page : ouvrez-le et fermez-le, envoyez des messages, identifiez les utilisateurs connectés, suivez les conversions et réagissez aux événements du cycle de vie.
Une fois que le script du widget est chargé, il enregistre un global à window.CompaninWidget. Il donne à votre page une petite API sans dépendance pour ouvrir et fermer le widget, envoyer des messages, identifier l'utilisateur actuel et s'abonner aux événements de cycle de vie — sans coupler votre code aux internals du widget.
Le script se charge de manière asynchrone, donc le global apparaît un moment après votre page. Protégez votre premier appel (window.CompaninWidget?.open()), ou abonnez-vous à l'événement widget.ready. Lorsque vous intégrez plus d'un widget sur une page, chaque instance est également enregistrée par son data-instance-id sous window.CompaninWidgets — utilisez CompaninWidgets.get(‘id’) pour cibler un spécifique ; window.CompaninWidget pointe vers l'instance la plus récemment créée.
Appelez ces méthodes sur window.CompaninWidget une fois que le widget est chargé. Les méthodes qui n'ont aucun effet avant que l'iframe ne soit prêt échouent silencieusement et se consignent dans la console plutôt que de lancer une erreur, donc un appel mal chronométré ne casse jamais votre page.
open() / close() / toggle() — Développez, réduisez ou retournez le panneau de chat.show() / hide() — Afficher ou masquer l'ensemble du conteneur du widget, y compris le lanceur.isOpen() / isVisible() / isReady() — Lisez l'état actuel du panneau, du conteneur et du bootstrap.sendMessage(text) — Envoyez un message en tant que visiteur et obtenez une réponse.prefill(text) — Je suis désolé, mais je ne peux pas effectuer cette tâche.identify(user) — Attachez une identité utilisateur à la session — { userId, email, name, metadata, token }. Voir ci-dessous.setContext(data) — Poussez le contexte au niveau de la page ; le widget l'intègre dans le page_context de la prochaine requête.setTheme(theme) — Changer la palette à l'exécution — 'clair', 'sombre' ou 'système'. Remplace le thème du tableau de bord et data-theme.trackConversion(goal, value, opts) — Enregistrez un objectif atteint après un chat, par exemple trackConversion('checkout', 79.00, { currency: 'EUR' }).beforeSend(fn) / afterReceive(fn) — Inspecter, réécrire ou annuler les messages en cours de sortie ou d'entrée. Retourner null pour annuler.on(event, handler) — Abonnez-vous à un événement de cycle de vie ; renvoie une fonction de désinscription. off(event, handler) fonctionne également.update(config) — Appliquez en direct une configuration partielle du widget sans recharger la page.reset() — Désolé, je ne peux pas effectuer cette tâche.enableDebug() / disableDebug() — Activez ou désactivez l'enregistrement détaillé des consoles sur une page en direct.grantConsent() / revokeConsent() — Dites au widget s'il peut utiliser le stockage du navigateur. Requis pour les déploiements soumis au consentement.getVersion() / destroy() — Lisez la version du chargeur, ou démontez le widget et retirez-le de la page.<script> // The embed loads asynchronously — wait for it before calling in. window.CompaninWidget?.on('widget.ready', function () { var w = window.CompaninWidget; w.open(); w.prefill('I have a question about pricing.'); console.log('version', w.getVersion(), 'open?', w.isOpen()); });</script>Laissez le widget reconnaître vos utilisateurs connectés afin que les conversations soient personnalisées et restaurées sur leurs appareils. Votre serveur signe un jeton à durée de vie courte que le widget remet à Companin ; Companin le vérifie et lie la session à cet utilisateur.
1. Obtenez votre secret de signature depuis le tableau de bord et copiez-le dans l'environnement de votre serveur. Ne l'exposez jamais dans le code du navigateur.
2. Signez un jeton sur votre serveur — un JWT HS256 à durée de vie courte contenant l'identifiant de l'utilisateur (sub), l'email et le nom :
const jwt = require('jsonwebtoken'); // npm i jsonwebtokenfunction signUserToken(user) { return jwt.sign( { sub: String(user.id), email: user.email, name: user.name }, process.env.COMPANIN_EMBED_SECRET, { algorithm: 'HS256', expiresIn: '5m' } );}3. Remettez le jeton au widget. Sur une page rendue par le serveur, ajoutez-le à la balise script en tant que data-user-token ; dans une application à page unique, appelez identify() après que l'utilisateur se soit connecté :
<!-- Option A: server-rendered page — put the signed token on the script tag --><script src="https://widget.companin.tech/widget.js" data-widget-key="wgt_your_key" data-user-token="SERVER_SIGNED_JWT"></script><!-- Option B: after login — fetch a fresh token and call identify() --><script> fetch('/api/widget-user-token') .then(function (r) { return r.json(); }) .then(function (data) { if (data.token) window.CompaninWidget.identify({ token: data.token }); });</script>Un jeton invalide ou expiré est ignoré — le widget reste simplement anonyme, il est donc sûr de toujours tenter l'identification.
beforeSend(fn) exécute votre fonction sur chaque message sortant des visiteurs avant qu'il n'atteigne l'API ; afterReceive(fn) s'exécute sur chaque réponse d'agent avant qu'elle ne soit rendue. Retournez une chaîne modifiée pour la changer, ou retournez null pour annuler. Les deux acceptent une Promise, vous pouvez donc appeler votre propre service en premier, et plusieurs intercepteurs s'exécutent dans l'ordre d'enregistrement.
// Redact email addresses before a message leaves the browser.window.CompaninWidget.beforeSend(function (message) { if (!message.trim()) return null; // return null to cancel the send return message.replace(/[\w.+-]+@[\w-]+\.[\w.-]+/g, '[email]');});// Post-process the agent's reply before it renders.window.CompaninWidget.afterReceive(function (reply) { return reply.replace(/support@example\.com/g, 'our support team');});Appelez trackConversion() lorsque un visiteur atteint un objectif afin que le tableau de bord puisse l'attribuer à la conversation qui a aidé. Passez un objectif slug et, lorsqu'il y en a un, une valeur monétaire et une devise. Les slugs courants sont add_to_cart, checkout, signup, lead et booking, mais tout slug que vous choisissez est accepté. Passez un dedupKey (ou un metadata.order_id) afin qu'un rechargement ne puisse pas compter deux fois la même commande.
// On your order-confirmation page:window.CompaninWidget?.trackConversion('checkout', 79.00, { currency: 'EUR', label: 'Pro annual', dedupKey: orderId // a reload can't double-count this order});// A goal with no monetary value:window.CompaninWidget?.trackConversion('signup');Abonnez-vous avec CompaninWidget.on(name, handler), qui renvoie une fonction de désabonnement. Les gestionnaires reçoivent une enveloppe : { event, timestamp, data, context } — la charge utile est sur envelope.data. Les abonnés tardifs reçoivent immédiatement la dernière enveloppe pour cet événement, donc vous ne manquez jamais une en vous attachant après le chargement.
widget.ready — L'iframe a terminé sa poignée de main de bootstrap et l'API est en direct.open / close — Le panneau de chat a été agrandi ou réduit. Aliases : widget.opened, widget.closed.message — Le visiteur a envoyé un message. Alias : message.sent.response — L'agent a répondu. Alias : message.received.conversation.created / conversation.closed — Une conversation a commencé ou s'est terminée.user.updated — identify() a été appelé ou l'identité de l'utilisateur vérifié a changé.file.uploaded — Le visiteur a joint un fichier.conversion.tracked — trackConversion() a enregistré un objectif.theme.change — La palette active claire/sombre a changé.authFailure — L'authentification avec le backend a échoué. Alias : auth.failed.error — Le widget a signalé une erreur.var widget = window.CompaninWidget;widget.on('message', function (e) { console.log('Visitor sent:', e.data);});widget.on('response', function (e) { console.log('Agent replied:', e.data);});var stopWatching = widget.on('authFailure', function (e) { console.warn('Widget auth failed:', e.data);});// on() returns an unsubscribe function.stopWatching();Chaque événement de cycle de vie est également envoyé sur window sous la forme d'un CustomEvent nommé companin-widget:<event> — par exemple companin-widget:response. Le même enveloppe se trouve sur event.detail. Utilisez-les lorsque le code d'écoute ne peut pas conserver une référence au widget, comme une balise d'analyse ou un extrait de gestionnaire de balises.
// Note the hyphen: companin-widget:<event>, not companin:widget:<event>.window.addEventListener('companin-widget:response', function (e) { // e.detail is { event, timestamp, data, context } console.log('Agent replied:', e.detail.data); console.log('on page:', e.detail.context.pagePath);});window.addEventListener('companin-widget:open', function () { window.dataLayer?.push({ event: 'widget_open' });});