Intégrer dans votre app

Le widget s’installe avec une seule balise script, et tout le reste de cette page en découle : quelle clé utiliser, comment le charger dans une single-page app, comment le monter en ligne plutôt qu’en flottant, et ce qu’une Content-Security-Policy stricte doit autoriser.

Récupérez votre clé d’intégration

Le widget s’authentifie avec une clé publiable. Les clés publiables peuvent figurer sans risque dans le code de votre page : elles identifient votre espace de travail mais ne portent aucune capacité secrète.

1. 1
   Ouvrez les clés d’API dans le tableau de bordAllez dans Paramètres → Clés d’API dans le tableau de bord de votre espace de travail.
2. 2
   Copiez la clé publiableCopiez la clé qui commence par pk_test_ pour le développement ou pk_live_ pour la production — jamais une clé secrète gak_, qui n’a sa place que sur votre serveur.
3. 3
   Faites correspondre la clé à l’environnementLe widget déduit l’environnement du préfixe de la clé ; ajoutez data-env seulement si vous devez le forcer explicitement.

La balise script

Collez la balise juste avant la fermeture de body sur chaque page où l’assistant doit apparaître. Elle doit conserver type="module" : le widget est un module ES et ne se charge pas sans.

<script
  type="module"
  src="https://cdn.syncanix.com/widget.js"
  data-key="pk_test_..."
  data-position="bottom-right"
  data-env="development"
></script>

C’est toute l’installation : le lanceur apparaît dans le coin choisi, et tout le reste se conçoit dans le tableau de bord. La liste complète des attributs se trouve dans la référence de configuration.

React, Vue et autres single-page apps

Dans une single-page app, l’installation la plus simple reste la balise statique dans votre index.html : le widget survit de lui-même à la navigation côté client. Si vous préférez piloter le montage depuis votre arbre de composants, injectez le script dans un effet et démontez au nettoyage :

import { useEffect } from 'react';

export function SyncanixWidget({ embedKey }: { embedKey: string }) {
  useEffect(() => {
    const script = document.createElement('script');
    script.type = 'module';
    script.src = 'https://cdn.syncanix.com/widget.js';
    script.setAttribute('data-key', embedKey);
    document.body.appendChild(script);
    return () => {
      window.syncanix?.unmount();
      script.remove();
    };
  }, [embedKey]);
  return null;
}

Le même schéma fonctionne partout où existent des hooks de montage et de nettoyage : onMounted/onUnmounted dans Vue, ngOnInit/ngOnDestroy dans Angular, onMount dans Svelte.

Monter en ligne plutôt qu’en flottant

Par défaut, le widget flotte sous forme de lanceur dans un coin de la page. Pour placer le chat dans votre propre mise en page — un panneau d’aide, une barre latérale, une page entière — utilisez data-chat-size="embedded" et pointez data-mount-target vers un sélecteur CSS du conteneur que le widget doit remplir :

<div id="assistant-panel"></div>

<script
  type="module"
  src="https://cdn.syncanix.com/widget.js"
  data-key="pk_live_..."
  data-chat-size="embedded"
  data-mount-target="#assistant-panel"
></script>

Transmettez l’identité de votre utilisateur

Sans identité, l’assistant traite chaque visiteur comme anonyme. Pour qu’il agisse au nom de l’utilisateur connecté, enregistrez un fournisseur de jeton : le widget l’appelle avant chaque tour, un jeton à jour est donc toujours envoyé. La configuration complète de chaque mode d’authentification se trouve dans authentifier vos utilisateurs.

window.syncanix?.setTokenProvider(async () => {
  // Called before each turn — return the signed-in user's current token.
  return auth.getTokenSilently();
});

Exigences de Content-Security-Policy

Si votre site applique une CSP stricte, autorisez ces trois éléments avant d’intégrer :

script-src  https://cdn.syncanix.com;
connect-src https://api.syncanix.com;
style-src   'unsafe-inline';

• script-src doit autoriser cdn.syncanix.com — d’où sont servis widget.js et ses fragments différés.
• connect-src doit autoriser api.syncanix.com — où le widget diffuse les conversations.
• style-src doit autoriser 'unsafe-inline' — le widget injecte ses styles dans son propre Shadow DOM, ils ne touchent donc jamais les styles de votre page.
• Les pages imposant Trusted Types fonctionnent sans modification : le widget n’alimente jamais de string sink.

Étapes suivantes