Widget-Konfiguration

Konfigurieren Sie das Widget mit data-*-Attributen am Script-Tag.

Sie konfigurieren das Widget über data-*-Attribute am Script-Tag. Alles, was das Widget von diesem Tag liest, steht unten — gruppiert nach Zweck: die Kerneinstellungen, die fortgeschrittenen, und die Attribute, die ein ganzes Verhalten einschalten.

<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>

Ein vollständiges Beispiel: Entwicklungsschlüssel, Launcher unten links, großes Panel, französische Oberfläche, Konfiguration sofort geladen.

Kernattribute

data-key — Ihr veröffentlichbarer Schlüssel (pk_test_… oder pk_live_…). Erforderlich.
data-enabled — auf false setzen, um das Skript zu laden, das Widget aber nicht einzuhängen (standardmäßig true).
data-position — Ecke des Starters: bottom-right (Standard), bottom-left, top-right oder top-left.
data-locale — legt Sprache und Schreibrichtung für diese Seite fest (zum Beispiel ar oder en-US). Ohne dieses Attribut folgt das Widget automatisch der Sprache Ihrer Seite.
data-chat-size — small (Standard), medium, large, fullscreen oder embedded.
data-env — development oder production (sonst aus dem Schlüsselpräfix abgeleitet).
data-theme — eine JSON-Zeichenkette mit Theme-Token-Überschreibungen.

Das Widget folgt der Sprache Ihrer Seite von selbst — ein Attribut ist nicht nötig. Es liest Ihr <html lang> und verlässt sich auf das, was auf dem Bildschirm steht, wenn Ihre Seite eine andere Schrift darstellt als sie angibt. Nutzen Sie Ihren eigenen Sprachumschalter, und der Chat folgt clientseitig, ohne Neuladen und ohne die Unterhaltung zu verlieren. Setzen Sie data-locale nur, wenn Sie das für eine Seite überschreiben möchten.

Die erste Nachricht Ihrer Besucherin oder Ihres Besuchers legt die Sprache der Unterhaltung fest, und dabei bleibt es auch, wenn danach die Sprache Ihrer Website gewechselt wird: Eine auf Hebräisch begonnene Unterhaltung antwortet weiter auf Hebräisch. Die Beschriftungen des Widgets und der KI-Hinweis folgen weiterhin Ihrer Seite, sodass der Hinweis immer in der gerade genutzten Sprache lesbar bleibt. Wer die Sprache wechseln möchte, sagt es einfach im Chat.

Erweiterte Attribute

data-origin — der Ursprung der Syncanix-API (standardmäßig die Produktions-API).
data-theme-name — wählt ein benanntes Design aus Ihrer Bibliothek; auto folgt der Hell/Dunkel-Einstellung der Host-Seite.
data-prompt-profile — führt auf dieser Seite ein bestimmtes Prompt-Profil aus, unter dem Namen, unter dem Sie es veröffentlicht haben. Nur veröffentlichte Profile sind benennbar; alles andere fällt auf Ihr aktives Profil zurück.
data-mount-target — ein CSS-Selektor, wohin ein eingebettetes Widget eingehängt wird.
data-api-base-url — wo Ihre eigene API liegt, wenn sie auf einem anderen Host als die Seite läuft. Ohne das Attribut gehen Aktionen an den Host der Seite selbst — richtig bei einem Ein-Host-Auftritt, falsch bei der üblichen app./api.-Trennung.
data-api-origins — eine kommagetrennte Liste weiterer Ursprünge, die ebenfalls Ihre API sind. Beobachtet wird nur Verkehr zu Ihren eigenen Ursprüngen — eine API auf einem separaten Host muss hier genannt werden, sonst wird sie bewusst ignoriert.
data-theme-vars — ordnet die Farbrollen des Widgets Ihren eigenen CSS-Variablennamen zu, als JSON. Wird live aufgelöst und folgt so von selbst Ihrem Hell/Dunkel-Umschalter; mit data-theme-source benennen Sie das Element, auf dem Ihre Variablen deklariert sind.
data-config-load — lazy (Einstellungen beim ersten Öffnen laden, Standard) oder eager (beim Einbinden).
data-executor — der Name einer globalen Funktion, die Browser-/Host-Aktionen ausführt.
data-token-provider — der Name einer globalen Funktion, die das Token des Endnutzers zurückgibt.
data-step-up-provider — der Name einer globalen Funktion, die die erhöhte Neuauthentifizierung auslöst.
data-headers-provider — der Name einer globalen Funktion, die zusätzliche Anfrage-Header zurückgibt.
data-client-witness — die passive, nur formbezogene Beobachtung des API-Verkehrs aktivieren (standardmäßig aus).
data-act-on-behalf-consent — eine einmalige Zustimmung „in Ihrem Namen handeln“ verlangen (standardmäßig aus).

Ein Verhalten einschalten

Diese konfigurieren weder Aussehen noch Ziel des Widgets — sie schalten ein ganzes Verhalten ein. Jedes ist aus, solange Sie es nicht hinzufügen.

data-trigger — ein CSS-Selektor für Schaltflächen auf Ihrer eigenen Seite, die den Chat öffnen sollen. Ein Navigationspunkt, ein Fußzeilen-Link, eine Leerzustand-Schaltfläche. Ein Klick schaltet das Panel um, und das Widget hält den Ausklappzustand der Schaltfläche für Screenreader korrekt angesagt.
data-ask-about — lässt Besucher etwas auf Ihrer Seite auswählen und den Assistenten dazu fragen. Standardmäßig aus; muss zusätzlich für den Arbeitsbereich eingeschaltet sein.
data-haptics — auf false setzen, damit das Widget beim Bestätigen einer Aktion kein Telefon vibrieren lässt. Standardmäßig an und für Besucher mit reduzierter Bewegung immer unterdrückt.
data-frame-mode — wie sich ein Widget in einem iframe verhält: auto (Standard), agent oder standalone. Nur relevant, wenn Ihre App Teile von sich in Frames einbettet.
data-frame-origins — eine kommagetrennte Liste exakter Ursprünge, deren eingerahmte Seiten Ihr oberstes Widget bedienen darf. Leer oder fehlend heißt keine — das ist die Voreinstellung.
data-capture-closed-roots — auf true setzen, wenn Teile Ihrer Seite mit einer fremden Komponentenbibliothek gebaut sind, in die der Assistent sonst nicht hineinsieht. Standardmäßig aus und nur nötig, wenn ein Bedienelement, das er bedienen können sollte, für ihn unsichtbar ist.

Daten vom Assistenten fernhalten

Der Assistent liest Ihre Seite, um zu wissen, was darauf steht. Diese drei entscheiden, was er sehen darf, damit ein Wert auf dem Bildschirm ihn nie erreichen muss — und gängige Formen personenbezogener Daten werden standardmäßig zurückgehalten.

data-block-selectors — eine kommagetrennte Liste von CSS-Selektoren für Bereiche, die der Assistent nie sehen darf. Ein passendes Element und alles darin wird bereits bei der Erfassung ausgeschlossen — nachweislich nicht vorhanden, nicht nachträglich entfernt. Markieren Sie den Container, nicht jedes einzelne Feld.
data-mask-selectors — eine kommagetrennte Liste von CSS-Selektoren, deren WERTE zurückgehalten werden, während das Feld selbst sichtbar bleibt. Der Assistent weiß, dass das Feld existiert, liest aber nie seinen Inhalt — dieselbe Behandlung wie bei der integrierten Schwärzung von Passwörtern und Karten.
data-mask-pii — standardmäßig aktiviert. Ein Wert, der wie eine E-Mail-Adresse, eine US-Sozialversicherungsnummer oder eine Kartennummer aussieht, wird zurückgehalten, selbst wenn kein Selektor ihn benennt. Es wird nur der Wert verborgen; das Feld bleibt sichtbar. Setzen Sie es nur dort auf false, wo Sie akzeptieren, dass diese Werte den Assistenten und das gespeicherte Transkript erreichen.

Nächste Schritte

Laufzeit-APISteuern Sie das Widget aus JavaScript.GestaltungWie sich das Widget Ihrer Marke anpasst.