@botfabrik/engine-webclient 4.111.1 → 4.113.0

package/README.md

@@ -298,6 +298,28 @@ Diese Konfiguration stellt sicher, dass sich Benutzer vor der Nutzung des Chats
 Falls dieses Property auf `false` ist, erscheint z.B. der FAB (Floating Action Button) auf der Webseite nicht. Der Chatbot kann via FAB nur mittels Bookmarklet verwendet werden.
 Diese Einstellung ist nützlich, wenn der Chatbot noch in Entwicklung ist und die Webagentur ihn bereits in der Webseite integrieren will. Wir können damit steuern, ob er auf der Webseite sichtbar ist oder nicht.
 
+### allowedEmbedOrigins
+
+Eine Liste von Domain-URLs, von denen aus der Chatbot in einem iframe eingebettet werden darf. Dies ist eine wichtige Sicherheitsfunktion, um zu kontrollieren, welche Webseiten den Chatbot integrieren können.
+
+- **[]** (leeres Array) - Nur die Server-eigene Domain ist erlaubt
+- **['https://example.com', 'https://www.example.com']** - Nur die aufgelisteten Domains sind erlaubt
+
+**Wichtig:** Diese Einstellung muss korrekt konfiguriert sein, damit die Script-Tag Integration funktioniert.
+
+### allowedResourceOrigins
+
+Eine Liste von Domain-URLs, von denen externe Ressourcen wie Stylesheets, Bilder und Fonts geladen werden dürfen. Dies ist eine Content Security Policy (CSP) Einstellung zur Kontrolle externer Ressourcen.
+
+- **[]** (leeres Array) - Nur die Server-eigene Domain ist als Ressourcen-Quelle erlaubt
+- **['https://fonts.googleapis.com', 'https://cdn.example.com']** - Nur die aufgelisteten Domains sind erlaubt
+
+Diese Einstellung betrifft:
+
+- **Stylesheets** (style-src): Externe CSS-Dateien
+- **Bilder** (img-src): Externe Bilder und Icons
+- **Fonts** (font-src): Externe Schriftarten (z.B. Google Fonts)
+
 ## Texte / Übersetzungen anpassen
 
 Sämtliche Texte des Webclients können angepasst werden. Dazu müssen im Bot-Projekt die Locale-Dateien modifiziert werden. Die anzupassenden Texte sind unter `website-messenger` aufzuführen.
@@ -481,6 +503,56 @@ Möchte man also z.B. beim grossen Client ein anderes Logo verwenden, kann man d
 
 Unter der Chatbot-Route unter "/embed/ des Servers (z.B. `http://localhost:3000/chatbot/embed`) läuft einen Beispielseite wie der Chatbot eingebetet werden kann. Dort gibt es ebenfalls einen Button, mit welchem das benötigte Snippet angezeigt werden kann. Das Aussehen kann im File `/public/webclient/embed/custom.css` jegliches CSS überschreiben (siehe [Beispiel](src/embed/custom.css)).
 
+### Script-Tag Integration
+
+Das Einbetten erfolgt über ein Script-Tag mit folgenden Attributen:
+
+**Wichtig:** Damit die Integration funktioniert, muss die Domain der Webseite in der server-seitigen Property `allowedEmbedOrigins` konfiguriert sein. Siehe [allowedEmbedOrigins](#allowedembedorigins).
+
+```html
+<script
+  id="chatbot"
+  data-server="https://my-chatbot.bubble-chat.ch"
+  data-expand-at-start="all"
+  data-link-handling="default"
+  defer
+  src="https://my-chatbot.bubble-chat.ch/webclient/embed/bundle.js"
+></script>
+```
+
+#### data-server (erforderlich)
+
+Die vollständige URL zum Chatbot-Server.
+
+Beim `data-server` können Query-Parameter angegeben werden, um dem Chatbot bei der Integration zusätzliche Informationen mitzuteilen.
+
+Beispiel: `data-server="https://my-chatbot.bubble-chat.ch?systemId=123&userRole=editor"`
+
+**Hinweis:** Die Query-Parameter `userId` und `sessionId` sind nicht erlaubt.
+
+#### data-expand-at-start (optional)
+
+Mit `data-expand-at-start` kann gesteuert werden, ob das Chatfenster beim Laden der Seite automatisch geöffnet werden soll. Die Option berücksichtigt dabei das verwendete Endgerät.
+
+- **"all"** - Das Chatfenster wird auf allen Geräten automatisch geöffnet.
+- **"desktop"** - Das Chatfenster wird nur auf Desktop-Geräten (≥768px Bildschirmbreite) automatisch geöffnet.
+- **"mobile"** - Das Chatfenster wird nur auf mobilen Geräten (<768px Bildschirmbreite) automatisch geöffnet.
+- **nicht gesetzt** (Standard) - Das Chatfenster bleibt geschlossen und muss vom Benutzer manuell geöffnet werden.
+
+**Wichtig:** Das Chatfenster wird nur automatisch geöffnet, wenn der Benutzer es nicht zuvor explizit geschlossen hat. Der Fensterstatus wird in einem Cookie (`bubble-chat-window-state`) für 8 Stunden gespeichert.
+
+**Hinweis:** Dieses Attribut übersteuert die Server-seitige Property `expandChatWindowAtStart`.
+
+#### data-link-handling (optional)
+
+Mit `data-link-handling` kann gesteuert werden, wie Links im Chatbot geöffnet werden.
+
+- **"default"** (Standard) - Links der gleichen Domain werden im selben Tab und Links einer anderen Domain werden in einem neuen Tab geöffnet.
+- **"existing-tab"** - Links werden immer im selben Tab geöffnet.
+- **"new-tab"** - Links werden immer in einem neuen Tab geöffnet.
+
+Weitere Details zur Integration finden sich im [Script-Tag README](./script-tag/README.md).
+
 ## Strategie zur Speicherung des Chatverlaufs
 
 Sämtliche Actions, die die Botengine ausführt, werden in der Datenbank gespeichert. Damit kann jeder beliebige Chatverlauf zu einem späteren Zeitpunkt wiederhergestellt werden.