Configuration du widget
Configurez le widget avec des attributs data-* sur la balise de script.
Vous configurez le widget avec des attributs data-* sur la balise script. Tout ce que le widget lit sur cette balise figure ci-dessous, groupé par rôle : les réglages de base, les avancés, et les attributs qui activent tout un comportement.
<script
type="module"
src="https://cdn.syncanix.com/widget.js"
data-key="pk_test_..."
data-position="bottom-left"
data-env="development"
data-chat-size="large"
data-locale="fr"
data-config-load="eager"
></script>Attributs principaux
- data-key — votre clé publiable (pk_test_… ou pk_live_…). Obligatoire.
- data-enabled — mettez false pour charger le script sans monter le widget (true par défaut).
- data-position — coin du lanceur : bottom-right (par défaut), bottom-left, top-right ou top-left.
- data-locale — fixe la langue et la direction pour cette page (par exemple ar ou en-US). Sans cet attribut, le widget suit automatiquement la langue de votre page.
- data-chat-size — small (par défaut), medium, large, fullscreen ou embedded.
- data-env — development ou production (sinon déduit du préfixe de la clé).
- data-theme — une chaîne JSON de surcharges de tokens de thème.
Le widget suit la langue de votre page tout seul : aucun attribut n'est nécessaire. Il lit votre <html lang> et, lorsque votre page affiche une écriture différente de celle qu'elle déclare, il se fie à ce qui est à l'écran. Utilisez votre propre sélecteur de langue et le chat suit, côté client, sans rechargement et sans perdre la conversation. N'utilisez data-locale que pour passer outre sur une page donnée.
Le premier message de votre visiteur fixe la langue de la conversation, et elle y reste même s'il change ensuite la langue de votre site : une conversation entamée en hébreu continue de répondre en hébreu. Les libellés du widget et l'avis IA suivent toujours votre page, si bien que l'avis reste lisible dans la langue qu'il consulte. S'il veut changer de langue, il lui suffit de le demander dans le chat.
Attributs avancés
- data-origin — l’origine de l’API Syncanix (par défaut, l’API de production).
- data-theme-name — sélectionne un design nommé de votre bibliothèque ; auto suit le réglage clair/sombre du site hôte.
- data-prompt-profile — exécute sur cette page un profil de prompt précis, par le nom sous lequel vous l’avez publié. Seuls les profils publiés peuvent être nommés ; toute autre valeur retombe sur votre profil en service.
- data-mount-target — un sélecteur CSS indiquant où monter un widget intégré.
- data-api-base-url — où vit votre propre API, si elle est sur un hôte différent de la page. Sans lui, les actions partent vers l’hôte de la page, ce qui convient à un site mono-hôte et pas à la séparation courante app./api.
- data-api-origins — une liste d’origines supplémentaires, séparées par des virgules, qui sont aussi votre API. Seul le trafic vers vos propres origines est observé : une API sur un hôte distinct doit donc être nommée ici, sinon elle est délibérément ignorée.
- data-theme-vars — associez les rôles de couleur du widget à vos propres noms de variables CSS, en JSON. Résolu en direct, il suit donc seul votre bascule clair/sombre ; associez-le à data-theme-source pour nommer l’élément où vos variables sont déclarées.
- data-config-load — lazy (charger les réglages à la première ouverture, par défaut) ou eager (au montage).
- data-executor — le nom d’une fonction globale qui exécute des actions du navigateur ou de l’hôte.
- data-token-provider — le nom d’une fonction globale renvoyant le jeton de l’utilisateur final.
- data-step-up-provider — le nom d’une fonction globale qui déclenche la réauthentification renforcée.
- data-headers-provider — le nom d’une fonction globale renvoyant des en-têtes de requête supplémentaires.
- data-client-witness — activez l’observation passive du trafic de l’API, sur sa forme uniquement (désactivé par défaut).
- data-act-on-behalf-consent — exigez un consentement unique « agir en votre nom » (désactivé par défaut).
Activer un comportement
Ceux-ci ne configurent ni l’apparence du widget ni sa cible — ils activent tout un comportement. Chacun est désactivé tant que vous ne l’ajoutez pas.
- data-trigger — un sélecteur CSS pour les boutons de votre propre page qui doivent ouvrir la conversation. Un élément de nav, un lien de pied de page, un bouton d’état vide. Un clic bascule le panneau, et le widget maintient l’état déplié du bouton correctement annoncé aux lecteurs d’écran.
- data-ask-about — permet à un visiteur de sélectionner un élément de votre page et d’interroger l’assistant à son sujet. Désactivé par défaut ; il doit aussi être activé pour l’espace de travail.
- data-haptics — mettez-le à false pour que le widget ne fasse pas vibrer le téléphone quand un visiteur approuve une action. Activé par défaut, et toujours supprimé pour un visiteur dont l’appareil demande moins d’animations.
- data-frame-mode — comment se comporte un widget dans une iframe : auto (par défaut), agent ou standalone. Pertinent seulement si votre app intègre des parties d’elle-même dans des frames.
- data-frame-origins — une liste d’origines exactes, séparées par des virgules, dont les pages en iframe peuvent être prises en charge par votre widget principal. Vide ou absent signifie aucune, ce qui est le défaut.
- data-capture-closed-roots — mettez-le à true si des parties de votre page reposent sur une bibliothèque de composants tierce dans laquelle l’assistant ne peut pas voir. Désactivé par défaut, et utile uniquement quand un contrôle qu’il devrait pouvoir manipuler lui est invisible.
Garder des données hors de l'assistant
L'assistant lit votre page pour savoir ce qu'elle contient. Ces trois options déterminent ce qu'il peut voir, afin qu'une valeur affichée n'ait jamais à lui parvenir — et les formats courants de données personnelles sont retenus par défaut.
- data-block-selectors — une liste de sélecteurs CSS séparés par des virgules pour les zones que l'assistant ne doit jamais voir. Un élément correspondant, et tout ce qu'il contient, est exclu dès la capture : réellement absent, et non retiré après avoir été lu. Marquez le conteneur, pas chaque champ.
- data-mask-selectors — une liste de sélecteurs CSS séparés par des virgules dont les VALEURS sont masquées alors que le champ lui-même reste visible. L'assistant sait que le champ existe mais ne lit jamais son contenu — le même traitement que la protection intégrée des mots de passe et des cartes.
- data-mask-pii — activé par défaut. Une valeur qui ressemble à une adresse e-mail, à un numéro de sécurité sociale américain ou à un numéro de carte est masquée même si aucun sélecteur ne la désigne. Seule la valeur est cachée ; le champ reste visible. Ne le mettez à false que là où vous acceptez que ces valeurs parviennent à l'assistant et à la transcription enregistrée.