Widget für Ihre Website

Das Widget ist der Chat, den Besucher auf Ihrer Website sehen. Es lädt Ihren veröffentlichten Bot und führt das gesamte Gespräch im Browser. Ohne Sprachmodell, ohne Anfragen an Drittanbieter und mit einer Größe von etwa 22 KB nach der Komprimierung. Der Chat mit einem Supportmitarbeiter wird aus einer separaten Datei geladen, nur wenn Sie ihn aktivieren.

Installation

Fügen Sie diese Zeile vor </body> auf jeder Seite ein, auf der der Bot erscheinen soll. Im Dashboard finden Sie sie mit Ihrem Schlüssel auf der Seite Installation.

<script src="https://cdn.kavchat.com/v1/kavchat.js" data-key="pk_live_..." async></script>

Den öffentlichen Schlüssel (pk_live_...) dürfen Sie in eine Seite einfügen. Den geheimen Schlüssel (sk_live_...) dürfen Sie niemals in eine Seite einfügen.

Attribute

<script
  src="https://cdn.kavchat.com/v1/kavchat.js"
  data-key="pk_live_..."
  data-locale="he"
  data-user-token="<identity JWT>"
  data-user-name="Dana"
  data-open="false"
  async></script>

JavaScript-API

Das Skript stellt window.Kavchat bereit:

Kavchat.init({
  publicKey: 'pk_live_...',
  apiBase: 'https://api.kavchat.com', // optional
  locale: 'he',                       // optional
  userToken: '<identity JWT>',        // optional
  userName: 'Dana',                   // optional
  open: false,                        // optional
  onScreen(screen, targetId) {},      // optional: "screen" buttons in your scripts
  onEvent(event) {},                  // optional: ready, unavailable, open, close, effect, ticket
});
Kavchat.open();
Kavchat.close();
Kavchat.toggle();
Kavchat.setUser({ token: '<identity JWT>', name: 'Dana' }); // on login; setUser(null) on logout
Kavchat.offset({ bottom: 80 });       // lift the launcher, e.g. above a cookie banner; offset(null) resets
Kavchat.destroy();

init ist nicht nötig, wenn das Skript-Tag data-key enthält. Ein erneuter Aufruf von init ersetzt das laufende Widget.

API aufrufen, bevor das Skript geladen ist

Das Skript-Tag verwendet async, daher wird Ihr Code möglicherweise zuerst ausgeführt. Erstellen Sie eine Warteschlange und fügen Sie die Aufrufe dort ein. Das Widget führt sie nach dem Laden der Reihe nach aus. init wird immer zuerst ausgeführt, und seine Einstellungen haben Vorrang vor den Attributen im Tag.

<script>
  window.Kavchat = window.Kavchat || { q: [] };
  Kavchat.q.push(['init', { publicKey: 'pk_live_...', onScreen: function (s, id) { location.href = '/' + s + '/' + id; } }]);
  Kavchat.q.push(['setUser', { token: '<identity JWT>', name: 'Dana' }]);
</script>
<script src="https://cdn.kavchat.com/v1/kavchat.js" async></script>

Jeder Eintrag in der Warteschlange hat die Form [methodName, ...args]. Auch nach dem Laden des Skripts funktioniert Kavchat.q.push(...) weiter und führt den Aufruf sofort aus. So funktioniert derselbe Code in beiden Fällen.

Platz für ein Cookie-Banner

Wenn Ihre Website ein festes Element am unteren Bildschirmrand hat, etwa ein Cookie-Banner, können Sie den Button, das Fenster und die Sprechblasen darüber platzieren. Dafür gibt es zwei Möglichkeiten: die CSS-Variable --kavchat-bottom oder den Befehl Kavchat.offset, der eine Zahl in Pixeln oder einen Längenwert wie 5rem annimmt. Der Versatz wird zur Höhe addiert, die im Verwaltungsbereich festgelegt ist. Wenn das Banner geschlossen wird, entfernen Sie die Variable oder rufen Sie offset(null) auf. Beide Möglichkeiten funktionieren auch auf Websites mit einer strengen CSP. Auf dem Smartphone öffnet sich das Fenster im Vollbildmodus und wird nicht verschoben.

/* while your cookie banner is shown */
body.cookie-banner-open { --kavchat-bottom: 80px; }

// works before or after the widget script loads
window.Kavchat = window.Kavchat || { q: [] };
Kavchat.q.push(['offset', { bottom: banner.offsetHeight + 12 }]);

// after the visitor makes a choice
Kavchat.q.push(['offset', null]);

Ereignisse

Die Funktion onEvent empfängt eines der folgenden Ereignisse:

Kavchat.init({
  publicKey: 'pk_live_...',
  onEvent(event) {
    if (event.type === 'ready') console.log('Bot version', event.version, event.offline ? '(offline copy)' : '');
    if (event.type === 'ticket') console.log('Request opened', event.number);
  },
});

Aktionen im Skript

• Ticket: Öffnet das Kontaktformular im Chat. Das Gesprächsprotokoll wird dem Ticket beigefügt.
• Link: Öffnet https:- und tel:-Links in einem neuen Tab (rel="noopener noreferrer"). Andere Linktypen werden nicht geöffnet.
• Ansicht: Ruft Ihre Funktion onScreen(screen, targetId) auf. Ohne diese Funktion hat der Button auf der Website keine Wirkung.

Ansichtenliste im Editor

Deklarieren Sie einmalig die Ansichten, die Ihre App öffnen kann, in der Option screens von Kavchat.init. Das SDK sendet die Liste selbstständig an Kavchat. Der Skripteditor bietet diese Ansichten dann mit ihren Namen in einer Auswahlliste statt in einem Freitextfeld an. Er fragt außerdem nach einer Element-ID, wenn eine Ansicht diese benötigt, und warnt bei Buttons, die auf eine nicht deklarierte Ansicht verweisen. Die Ansichtenliste muss niemand von Hand im Dashboard eingeben.

Kavchat.init({
  publicKey: 'pk_live_...',
  screens: [
    { id: 'orders', label: 'My orders' },
    { id: 'product', label: 'Product page', needsTarget: true }, // the button also carries a product id
  ],
  onScreen(screen, targetId) {
    location.href = targetId ? `/${screen}/${targetId}` : `/${screen}`;
  },
});

• id ist der Wert, der an onScreen übergeben wird: lateinische Buchstaben, Ziffern, _, . und -, bis zu 40 Zeichen. label ist der Name, den der Administrator sieht, bis zu 60 Zeichen. Bis zu 100 Ansichten. Ungültige Einträge und doppelte IDs werden weggelassen.
• needsTarget: Der Button enthält auch eine Element-ID (zum Beispiel eine Produkt-ID), die als targetId an onScreen übergeben wird.
• Die Liste wird nach dem Laden der Version im Hintergrund gesendet, nur bei Änderungen oder einmal pro Woche. Fehler bleiben unbemerkt; beim nächsten Start wird der Versand erneut versucht. Für den Nutzer ist nichts sichtbar.
• Die registrierten Ansichten erscheinen im Dashboard unter Bot, Einstellungen, „App-Ansichten“, zusammen mit den Plattformen, die die jeweilige Ansicht gemeldet haben. Eine aus der App entfernte Ansicht können Sie dort löschen.

Ihre Nutzer identifizieren

Um Gesprächen und Tickets Ihre eigene Nutzer-ID zuzuordnen oder den Bot nur Testnutzern anzuzeigen, signieren Sie auf Ihrem Server ein JWT und übergeben es über data-user-token oder userToken. Wenn sich ein Nutzer an- oder abmeldet, rufen Sie Kavchat.setUser(...) auf. Das Widget sendet das Token bei jedem Aufruf im Header Authorization: Bearer <token>. Angemeldete Nutzer können ein Ticket erstellen, ohne eine E-Mail-Adresse oder Telefonnummer anzugeben. So erstellen Sie das Token: Nutzer identifizieren.

Content Security Policy

Das Widget funktioniert auf Websites mit strenger CSP, ohne 'unsafe-inline' und ohne 'unsafe-eval'. Sie müssen lediglich unsere beiden Quellen zulassen:

script-src https://cdn.kavchat.com;
connect-src https://api.kavchat.com;

Die Stile werden als constructable stylesheets im Shadow DOM geladen. Daher müssen Sie style-src nicht ändern. Wenn der Bot ein eigenes Bild hat oder Bilder in den Skripten vorkommen, fügen Sie den Server, von dem diese geladen werden, zu img-src hinzu. Das Widget lädt keine Inhalte aus anderen Quellen und öffnet kein iframe.

Chat mit einem Supportmitarbeiter

Auf Ihrer Website müssen Sie nichts einrichten. Wenn Sie den Chat mit Supportmitarbeitern im Verwaltungsbereich aktivieren, lädt das Widget eine zusätzliche Datei, kavchat-live.js, aus demselben Ordner und in derselben Version wie kavchat.js. Websites ohne Chat mit Supportmitarbeitern laden diese Datei gar nicht herunter.

• Die Option: Neben „Team kontaktieren“ erscheint die Option „Mit Supportmitarbeiter chatten“, erst nachdem der Server bestätigt hat, dass ein Mitarbeiter verfügbar ist. Außerhalb der Geschäftszeiten oder wenn alle Mitarbeiter beschäftigt sind, wird nur das Kontaktformular angezeigt. Daneben steht eine kurze Erklärung und, sofern bekannt, der Zeitpunkt, zu dem das Team wieder erreichbar ist. Ist das monatliche Kontingent aufgebraucht, erscheint das Formular ohne Erklärung.
• Die Anfrage: Gäste geben eine E-Mail-Adresse oder Telefonnummer an, falls kein Mitarbeiter rechtzeitig verfügbar wird. Ein Name und eine erste Nachricht können ebenfalls hinzugefügt werden. Ist mehr als eine Abteilung geöffnet, wird eine Abteilung ausgewählt. Identifizierte Nutzer (userToken) müssen keine Kontaktdaten eingeben. Kann kein Mitarbeiter den Chat annehmen, öffnet sich das Kontaktformular mit den bereits eingegebenen Angaben.
• Die Wartezeit: Angezeigt werden „Warten auf einen Supportmitarbeiter“ mit einem Countdown bis zum Ende der von Ihnen festgelegten Wartezeit sowie die Buttons „Stattdessen Nachricht hinterlassen“ und „Chat beenden“. Besucher können bereits während der Wartezeit schreiben. Nach Ablauf der Zeit wird der Chat automatisch zu einem Ticket. Der Besucher sieht die Ticketnummer und den Hinweis, dass kein Mitarbeiter rechtzeitig verfügbar war.
• Das Gespräch: Name des Mitarbeiters, Nachrichten, Tippanzeige, Übergabe an einen anderen Mitarbeiter und Beenden des Chats. Alles, was vom Server kommt, wird als reiner Text angezeigt, ohne HTML und ohne Links. Screenreader lesen neue Nachrichten vor. Bei geschlossenem Fenster erscheint ein Punkt auf dem schwebenden Chat-Button.
• Echtzeit: Die Verbindung erfolgt über Server-Sent Events. Wird sie unterbrochen, versucht das Widget in zunehmend größeren Abständen, die Verbindung wiederherzustellen, und ruft alles Versäumte ab. So geht keine Nachricht verloren und keine erscheint doppelt. In Netzwerken, die diese Verbindung blockieren, wechselt das Widget zu wiederholten Abfragen (Long Polling). Jede Nachricht hat eine ID, daher erzeugt ein erneuter Versuch kein Duplikat. Nicht gesendete Nachrichten werden markiert und lassen sich durch Antippen erneut senden.
• Neuladen: Die Zugangsberechtigung für den Chat wird je öffentlichem Schlüssel und Gespräch in localStorage gespeichert, niemals in der URL. Sie gilt bis zu 12 Stunden oder bis zum Ende des Chats. So wird nach dem Neuladen oder einem Seitenwechsel das gesamte Gespräch wiederhergestellt: zuerst der Teil mit dem Bot, danach der Teil mit dem Supportmitarbeiter.
• Ohne Preflight: Die Aufrufe werden ohne spezielle Header gesendet. Der Anfrageinhalt ist JSON und wird als text/plain übertragen.

KI-Antworten (Premium)

Auf Ihrer Website müssen Sie nichts einrichten. Wenn Sie KI-Antworten im Verwaltungsbereich aktivieren (mit Ihrem eigenen Schlüssel eines KI-Anbieters), wird eine Frage, die kein Skript beantwortet, an Kavchat gesendet. Während der Wartezeit von bis zu 20 Sekunden zeigt der Chat an, dass der Bot schreibt. Die Antwort erscheint als reiner Text mit dem kleinen Hinweis „KI-Antwort“ in der Sprache der Oberfläche. Darunter stehen ein Button zu einem verwandten Thema, falls vorhanden, und der Button „Team kontaktieren“.

Wenn keine Antwort vorliegt, die Anfrage fehlschlägt, zu lange dauert oder das Limit überschritten wird (10 Antworten pro Gespräch innerhalb von jeweils 15 Minuten), zeigt der Chat seine übliche Meldung „Ich habe keine Antwort gefunden“. Die Frage erscheint weiterhin im Bericht zu unbeantworteten Fragen. KI-Antworten werden wie jede andere Nachricht im gespeicherten Gespräch aufbewahrt.

So verhält sich das Widget

• Isolation: Alles wird innerhalb eines Shadow DOM dargestellt. Ihr CSS beeinflusst das Widget nicht, und das CSS des Widgets beeinflusst Ihre Seite nicht.
• Cache: Der veröffentlichte Bot wird je öffentlichem Schlüssel zusammen mit seinem ETag in localStorage gespeichert. Bei jedem Laden wird der Header If-None-Match gesendet. Hat sich nichts geändert, antwortet der Server mit 304. Ohne Netzwerkverbindung verwendet das Widget die gespeicherte Kopie und zeigt einen entsprechenden Hinweis an.
• Gespräche: Eine zufällige Gesprächs-ID wird in sessionStorage gespeichert, sodass dasselbe Gespräch beim Seitenwechsel fortgesetzt wird.
• Chat mit einem Supportmitarbeiter: Ein offener Chat wird in localStorage gespeichert und auf der nächsten Seite wiederhergestellt.
• Daten: Der Gesprächsverlauf wird etwa 2 Sekunden nach jeder Aktion gemeldet und auch dann, wenn die Seite ausgeblendet wird.
• Kavchat-Logo: Wird in allen Tarifen angezeigt. Mit Premium können Sie es in den Bot-Einstellungen ausblenden.
• Barrierefreiheit: Das Fenster ist ein Dialog mit einer zugänglichen Beschriftung. Der Fokus wechselt in den Dialog und wieder zurück. Esc schließt ihn. Die Buttons sind echte Buttons, neue Bot-Nachrichten werden vorgelesen, und Animationen werden reduziert, wenn der Besucher diese Einstellung gewählt hat.

Installation über npm

In einer Single-Page-App können Sie das Widget zusammen mit Ihrem Code bündeln, statt es über das Skript-Tag zu laden:

yarn add @kavchat/widget
# or: npm install @kavchat/widget

import { createWidget } from '@kavchat/widget';

const widget = createWidget({ publicKey: 'pk_live_...' });
await widget.ready;
widget.open();