Handbuch · Kapitel 28 · Teil G Entwickler
Einbettungs-Referenz
Wozu
Der Baukasten erzeugt den Einbettungs-Code; wer ihn von Hand schreibt, in Vorlagen einbaut oder mit eigenem JavaScript verbindet, findet hier alle Attribute, Variablen, Ereignisse und Endpunkte. Alles Folgende gilt für den Script-Tag, den Kapitel 8 und 9 beschreiben.
Der Chat-Lader
<script src="https://<instanz>/js/embed.js"
data-project="93"
data-title="Musterfirma Service-Chat"
data-accent="#1f4e79"></script>Der Lader holt Stylesheet, Chat-Logik und bei Bedarf die Sprachfunktion selbst nach und liest die Einstellungen der Sammlung vom Server. Nur Abweichungen stehen als Attribute am Tag.
Sammlung, Assistent, Sprache
| Attribut | Bedeutung |
|---|---|
data-project | Nummer der Sammlung. Pflicht. |
data-task | Nummer eines Assistenten. Begrüßung, Einstiegsfragen, Akzentfarbe und Wissens-Scope kommen dann aus dem Profil. |
data-language | Sprache der Seite; auto liest sie aus <html lang>. Antworten, Wissensbasis und Texte folgen ihr. |
data-llm | Nummer einer weiteren LLM-Konfiguration der Sammlung. |
data-endpoint | Nur für Sonderfälle: eine andere Adresse der Instanz. |
Darstellung und Verhalten
| Attribut | Bedeutung |
|---|---|
data-mode="inline" | Fest in der Seite statt als Blase; data-target="#selektor" montiert in ein Element, sonst hinter dem Script-Tag. |
data-position | Ecke der Blase: bottom-right, bottom-left, top-right, top-left. |
data-offset-x, data-offset-y | Abstand der Blase von den Rändern in Pixeln. |
data-open="1" | Panel startet geöffnet. data-open-delay="5" nach Sekunden, data-open-scroll="50" ab Scrolltiefe in Prozent. |
data-open-selector | CSS-Selektoren eigener Elemente, deren Klick das Panel öffnet. |
data-remember="0" | Merkt sich offen/geschlossen nicht mehr für den Besuch. |
data-mobile | full, bubble oder hidden auf Smartphones. |
data-pages | Pfade, auf denen der Chat lädt; ! schließt aus: /support/, !/support/intern. |
data-stream="0" | Antworten ohne Streaming. |
data-voice="1" | Sprach-Chat an, wenn die Sammlung ihn anbietet. |
data-off | Funktionen dieser Einbettung ausblenden, mit Komma: upload, feedback, sources, reset, simple, help, escalation, attest. Das Mikrofon steuert data-voice. |
Aussehen
| Attribut | Bedeutung |
|---|---|
data-theme | light, dark oder auto nach Systemeinstellung. |
data-accent | Akzentfarbe #rrggbb. |
data-header, data-header-text | Kopfzeile und ihre Schrift. |
data-text, data-bg, data-surface, data-border | Textfarbe, Hintergrund, Eingabefeld und Knöpfe, Rahmen. |
data-bubble, data-user-bubble | Antwort- und Besucher-Blase. |
data-chip-hover, data-send-hover | Farben beim Überfahren der Einstiegsfragen und des Senden-Knopfs. |
data-radius | Eckenradius des Chats in Pixeln. |
data-shape | Bedienelemente: leer = rund, square = dezent gerundet, sharp = eckig. |
data-shadow="0" | Ohne Schatten. |
data-font, data-font-size | Schriftfamilie und Größe in Pixeln. |
data-width, data-height | Maße des Panels in Pixeln. |
data-css="0" | Kein Stylesheet laden; Sie liefern das CSS (siehe Variablen). |
Texte und Links
| Attribut | Bedeutung |
|---|---|
data-title, data-greeting, data-label, data-placeholder | Titelzeile, Begrüßung, Beschriftung neben der Blase, Platzhalter. Mit data-language="auto" kommen die Texte je Sprache vom Server; die Attribute überschreiben sie. |
data-privacy-url, data-help-url | Datenschutz-Link im Widget und Hilfe-Link hinter dem ?-Knopf. |
Einwilligung
| Attribut | Bedeutung |
|---|---|
data-consent | cookiebot:<Kategorie>, usercentrics:<Dienst>, event:<Name> oder cookie:<Name>[=<Wert>]. Das Widget lädt erst nach Einwilligung. |
data-consent-text | Text an der Stelle des Chats bis dahin, nur bei fester Einbettung. |
Beim Modus event löst Ihre Website nach der Zustimmung ein Ereignis mit dem angegebenen Namen auf window aus.
Angemeldete Besucher
data-user-token übergibt das signierte Token (Kapitel 13). Alternativ schickt Ihre Seite es nach dem Laden mit dem Ereignis aic:user-token. Das Token ist ein HS256-JWT, signiert mit dem Identitäts-Geheimnis der Sammlung, mit den Claims sub (Pflicht), exp (Pflicht, höchstens 24 Stunden), name, groups (Liste) und attrs (Objekt).
JavaScript-Schnittstelle
window.aicChat steht nach dem Laden bereit: open(), close(), toggle(), isOpen() und ask("Frage"), das eine Frage stellt, als käme sie vom Besucher.
Ereignisse auf document:
| Ereignis | Wann |
|---|---|
aic:ready | Das Widget ist geladen. |
aic:open, aic:close | Das Panel wurde geöffnet oder geschlossen. |
aic:sent, aic:answer | Eine Frage wurde gesendet, eine Antwort ist da. |
aic:navigate | Der Besucher klickt eine Quelle oder einen Link; für Websites, die Seitenwechsel selbst steuern. |
aic:help | Das Hilfe-Overlay wird geöffnet. |
aic:lang | Die Gesprächssprache wurde erkannt oder gewechselt. |
aic:restored | Ein Gesprächsverlauf wurde aus dem Sitzungsspeicher wiederhergestellt. |
CSS-Variablen
Mit data-css="0" liefern Sie das Stylesheet selbst. Der Baukasten erzeugt eine CSS- oder SCSS-Vorlage mit allen Variablen; die wichtigsten:
| Variable | Bedeutung |
|---|---|
--aic-chat-primary | Akzentfarbe. |
--aic-chat-bg, --aic-chat-surface, --aic-chat-text, --aic-chat-muted, --aic-chat-border | Grundfarben. |
--aic-chat-assistant-bg, --aic-chat-user-bg | Blasen. |
--aic-chat-chip-hover, --aic-chat-send-hover | Hover-Farben. |
--aic-chat-radius, --aic-chat-shadow, --aic-chat-font, --aic-chat-font-size | Rundung, Schatten, Schrift. |
--aic-embed-accent, --aic-embed-header-bg, --aic-embed-header-text, --aic-embed-width, --aic-embed-height, --aic-embed-x, --aic-embed-y, --aic-embed-radius, --aic-embed-shadow | Blase und Panel. |
Der Such-Lader
<script src="https://<instanz>/js/search-embed.js"
data-project="93"
data-target="#site-search"></script>| Attribut | Bedeutung |
|---|---|
data-project | Nummer der Sammlung. Pflicht. |
data-language | Suchsprache; auto liest <html lang>. |
data-mode | hybrid, keyword oder semantic. |
data-limit | Treffer je Seite, 5 bis 50. |
data-live="1" | Suche beim Tippen. |
data-target | Element, in das die Suche gesetzt wird. |
data-title, data-placeholder, data-button | Überschrift, Platzhalter, Knopftext. Je weiterer Sprache mit Sprachzusatz, etwa data-title-en; bei data-language="auto" gilt die Fassung der Seitensprache, sonst das Attribut ohne Zusatz. Der Baukasten schreibt sie. |
data-accent, data-border, data-shape, data-font | Aussehen. |
data-css="0" | Kein Stylesheet; Variablen --aic-s-primary, --aic-s-border, --aic-s-muted, --aic-s-text, --aic-s-font, --aic-s-radius. |
Nach dem Laden steht window.aicSearchInit für Seiten bereit, die die Suche selbst montieren; ein Klick auf einen Treffer löst aic:search-navigate aus.
Öffentliche Endpunkte
| Adresse | Zweck |
|---|---|
/api/chat, /api/chat/stream | Fragen des Widgets, gestreamt oder am Stück. |
/api/chat/help, /api/chat/starters, /api/chat/attest | Einstellungen und Hilfetext der Einbettung, automatische Einstiegsfragen, Nachweis der Verarbeitungsregion. |
/api/search | Die Suche. |
/api/mcp | Endpunkt für KI-Agenten (Kapitel 14). |
/js/embed.js, /js/search-embed.js | Die Lader, mit Versionsstempel. |
Alle prüfen die erlaubten Websites der Sammlung. Nutzt die einbettende Seite eine Content-Security-Policy, muss die Adresse der Instanz in script-src, style-src, connect-src und img-src stehen, für den Sprach-Chat zusätzlich die WebSocket-Adresse in connect-src.
Siehe auch
- Kapitel 8 · Chat einbetten
- Kapitel 9 · Suche einbetten
- Kapitel 13 · Angemeldete Besucher
- Kapitel 21 · Einwilligung und Cookie-Banner