Flutter

Das Paket kavchat_flutter ergänzt Ihre Flutter-App um einen skriptbasierten Support-Chat: Buttons, Erkennung freier Texteingaben, ein Formular zum Erstellen von Tickets, eine auch offline nutzbare Kopie des Bots und eine Rechts-nach-links-Darstellung für Hebräisch und Arabisch.

Installation

dependencies:
  kavchat_flutter: ^0.0.11

Das Paket bringt http, shared_preferences (Versionscache und gespeicherter Gesprächsverlauf) und url_launcher (Links in Skripten) mit. Um tel:-Links unter Android 11 und neuer zu öffnen, ergänzen Sie in AndroidManifest.xml einen <queries>-Eintrag für das Schema tel sowie einen weiteren für https, um Weblinks zu öffnen (siehe README von url_launcher). Unter iOS ist LSApplicationQueriesSchemes nur erforderlich, wenn Sie selbst canLaunchUrl aufrufen.

Verwendung

final kavchat = KavchatController(
  publicKey: 'pk_live_...',
  // apiBase: 'https://api.kavchat.com', // default
  // locale: 'he',                        // default: device language if translated, else the bot language
  onScreen: (screen, targetId) => navigatorKey.currentState?.pushNamed('/$screen', arguments: targetId),
);

Scaffold(
  floatingActionButton: KavchatLauncher(controller: kavchat), // hidden while the bot is off
);

// or open it yourself
showKavchat(context, kavchat);

// or embed the screen in your own route
KavchatChat(controller: kavchat, onClose: () => Navigator.pop(context));

Erstellen Sie den Controller einmalig (zum Beispiel in einem State oder Provider) und rufen Sie dispose() auf, wenn die Komponente, die ihn hält, freigegeben wird.

KavchatLauncher ist ein FloatingActionButton und wird über Scaffold.floatingActionButtonLocation positioniert. Die Einstellung kavchat.settings?.position (start oder end) gibt an, welche Seite im Dashboard gewählt wurde.

Wenn im Dashboard eine Nachricht neben dem Chat-Button eingerichtet ist (eine Sprechblase, ein gebogener Text über dem Button, der Button selbst, der sich zu einer Kapsel mit Text erweitert, oder eine vom Button ausgehende Linie mit den ersten Auswahlmöglichkeiten des Bots), zeigt KavchatLauncher sie nach der eingestellten Verzögerung an, höchstens einmal pro Tag. Wenn Sie auf eine Option an der Linie tippen, öffnet sich der Chat mit dieser Auswahl, als wäre sie im Chat gewählt worden. Wird die Nachricht geschlossen oder der Chat geöffnet, bleibt die Nachricht bis zum nächsten Tag ausgeblendet. Bei geöffnetem Chat wird sie nicht angezeigt. Ist auf dem Gerät die Einstellung für reduzierte Bewegung aktiviert, erscheint die Nachricht ohne Animation. Bei aktivierter Option „Nicht auf Smartphones anzeigen“ erscheint sie nur auf Tablets (wenn die kürzere Bildschirmseite mindestens 600 Punkte misst). Auf Smartphones zeigt die Linie bis zu zwei Optionen. KavchatLauncher(controller: kavchat, attention: false) deaktiviert die Anzeige der Nachricht.

Wenn im Design ein Gesicht als Button-Symbol gewählt ist, blinzelt es gelegentlich, solange der Button nicht verwendet wird. Das Gesicht blinzelt nicht, wenn der Chat geöffnet ist, die App im Hintergrund läuft oder reduzierte Bewegung eingestellt ist.

Der Bot wird nicht angezeigt (der schwebende Button erscheint nicht und KavchatChat zeigt „Nicht verfügbar“), wenn die Version auf enabled: false gesetzt ist: Der Bot ist ausgeschaltet, nur für Testnutzer freigegeben und der Nutzer gehört nicht dazu, oder das Kontingent ist aufgebraucht (reason: 'quota').

Identitätstoken

Signieren Sie für angemeldete Nutzer ein kurzes JWT auf Ihrem Server mit dem geheimen Schlüssel (niemals in der App, siehe Nutzer identifizieren) und übergeben Sie es:

KavchatController(publicKey: 'pk_live_...', userToken: jwt, userName: 'Dana');
await kavchat.setUser(token: newJwt, name: 'Dana'); // after login
await kavchat.setUser(token: null);                 // after logout

Das Token wird bei jedem Aufruf im Header Authorization: Bearer <token> gesendet. Mit einem Token sind im Ticketformular weder E-Mail-Adresse noch Telefonnummer erforderlich, und der Nutzer kann als Mitglied der Testgruppe erkannt werden. setUser lädt die Version neu. Bei einem anderen Nutzer beginnt ein neues Gespräch, sodass ein auf dem Gerät gespeicherter Gesprächsverlauf nie auf ein anderes Konto übertragen wird.

Links, Ansichten und Ticketformular

• Buttons vom Typ link öffnen Links über url_launcher, ausschließlich für https: und tel:. Links in Bot-Nachrichten: nur https:.
• Buttons vom Typ screen rufen onScreen(screen, targetId) auf. Ohne diese Funktion haben sie keine Wirkung.
• Der Button „Team kontaktieren“ öffnet das integrierte Formular (Name, E-Mail-Adresse, Telefonnummer, Betreff und Nachricht, mit angehängtem Gesprächsverlauf). Nach dem Absenden wird die Ticketnummer angezeigt.

Ansichtenliste im Editor

Deklarieren Sie einmalig in KavchatController(screens: ...) die Ansichten, die Ihre App öffnen kann. 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. Der Editor fragt auch nach einer Element-ID, wenn eine Ansicht sie benötigt, und warnt bei Buttons, die auf eine nicht deklarierte Ansicht verweisen. Die Ansichtenliste muss nicht manuell im Dashboard eingegeben werden.

final kavchat = KavchatController(
  publicKey: 'pk_live_...',
  screens: const [
    KavchatScreen(id: 'orders', label: 'My orders'),
    KavchatScreen(id: 'product', label: 'Product page', needsTarget: true), // the button carries a targetId
  ],
  onScreen: (screen, targetId) => navigatorKey.currentState?.pushNamed('/$screen', arguments: targetId),
);
// later, to replace the list: await kavchat.registerScreens([...]);

• id ist der Wert, den onScreen erhält: lateinische Buchstaben, Ziffern, _, . und -, bis zu 40 Zeichen. label ist der Name, den der Administrator sieht, mit bis zu 60 Zeichen. Bis zu 100 Ansichten. Ungültige Einträge und doppelte IDs werden weggelassen.
• needsTarget: Der Button enthält zusätzlich 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 das Senden erneut versucht. Für den Nutzer ist nichts davon 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.

RTL

Der Chat legt seine eigene Directionality anhand der Oberflächensprache fest: he und ar von rechts nach links, alle anderen von links nach rechts. Die Ausrichtung Ihrer App bleibt unverändert. Jede Sprechblase bestimmt ihre Richtung außerdem anhand des ersten Buchstabens mit eindeutiger Schreibrichtung, damit auch gemischte Inhalte richtig lesbar sind. Oberflächensprache und Skriptsprache sind voneinander unabhängig: Ein englischsprachiger Bot kann bei locale: 'ar' Buttons wie „Zurück“ auf Arabisch anzeigen.

Farben und Branding

Die Farben stammen aus der Bot-Einstellung primaryColor. Darauf angezeigter Text ist je nach WCAG-Kontrast schwarz oder weiß. Eine zu helle Farbe wird dort, wo sie als Textfarbe dient, durch eine dunkle ersetzt. So ändern Sie die Farben:

KavchatLauncher(controller: kavchat, theme: KavchatThemeData.fromColor(const Color(0xFF0F766E)));
KavchatChat(controller: kavchat, theme: KavchatThemeData.fromHex('#0f766e').copyWith(background: Colors.white));

Der Hinweis „Bereitgestellt von Kavchat by maxsave“ wird in allen Tarifen mit einem Link zu kavchat.com angezeigt. Mit Premium können Sie ihn in den Bot-Einstellungen ausblenden.

Live-Chat mit einem Mitarbeiter

Zum Einstieg ist keine Einrichtung nötig. Sobald Sie den Live-Chat mit Mitarbeitern im Dashboard aktivieren, erscheint die Option im Chat Ihrer App genauso wie im Website-Widget.

• Die Option: „Mit einem Mitarbeiter chatten“ erscheint vor „Team kontaktieren“, und erst, nachdem der Server bestätigt hat, dass ein Mitarbeiter verfügbar ist. Beim Antippen des Buttons wird die Verfügbarkeit erneut geprüft. Außerhalb der Geschäftszeiten oder wenn alle Mitarbeiter beschäftigt sind, wird nur das Ticketformular angezeigt, mit einer kurzen Erklärung und, falls bekannt, dem Zeitpunkt, zu dem das Team wieder erreichbar ist. Ist das monatliche Kontingent aufgebraucht, erscheint das Formular ohne Erklärung.
• Die Anfrage: Gäste hinterlassen eine E-Mail-Adresse oder Telefonnummer, falls nicht rechtzeitig ein Mitarbeiter frei wird. Sie können auch einen Namen und eine erste Nachricht ergänzen. Ist mehr als eine Abteilung geöffnet, wählen sie eine Abteilung aus. Identifizierte Nutzer (userToken) müssen keine Kontaktdaten eingeben. Kann kein Mitarbeiter den Chat übernehmen, öffnet sich das Ticketformular mit den bereits eingegebenen Angaben.
• Die Wartezeit: Angezeigt wird „Warten auf einen Mitarbeiter“ mit einem Countdown bis zum Ende der von Ihnen festgelegten Wartezeit. Daneben stehen die Buttons „Stattdessen Nachricht hinterlassen“ und „Chat beenden“. Nutzer können bereits während der Wartezeit schreiben. Nach Ablauf der Zeit wird der Chat automatisch in ein Ticket umgewandelt. Angezeigt werden die Ticketnummer und ein Hinweis, dass nicht rechtzeitig ein Mitarbeiter frei wurde.
• Das Gespräch: Name des Mitarbeiters, Nachrichten, Tippanzeige, Weiterleitung an einen anderen Mitarbeiter und Beenden des Chats. Alle Inhalte vom Server werden als reiner Text ohne Links angezeigt.
• In Echtzeit: Eine Server-Sent-Events-Verbindung über eine gestreamte http-Antwort. Bricht die Verbindung ab, verbindet sich der Chat in zunehmend größeren Abständen erneut und lädt alles nach, was verpasst wurde. So geht keine Nachricht verloren oder erscheint doppelt. In Netzwerken, die diese Verbindung blockieren, und in Flutter Web arbeitet der Chat mit wiederholten Abfragen (Long Polling). Jede Nachricht hat eine ID, damit ein erneuter Versuch kein Duplikat erzeugt. Nicht gesendete Nachrichten werden markiert und lassen sich durch Antippen erneut senden.
• Hintergrund und Neustart: Wechselt die App in den Hintergrund (paused, hidden), wird die Verbindung geschlossen. Kehrt sie in den Vordergrund zurück (resumed), lädt der Chat die verpassten Inhalte nach. Der Zugangsnachweis für den Chat gilt bis zu 12 Stunden oder bis zum Ende des Gesprächs und wird im von Ihnen gewählten Speicher abgelegt. So erscheint ein laufender Chat nach einem Neustart der App wieder auf dem Bildschirm. Der Nachweis wird weder in einer URL gespeichert noch ins Log geschrieben.
• Keine Push-Benachrichtigungen in dieser Version: Nachrichten vom Mitarbeiter kommen nur an, solange die App geöffnet ist.

Wir empfehlen, den Zugangsnachweis in einem sicheren Speicher abzulegen (Keychain unter iOS, Keystore unter Android), zum Beispiel mit flutter_secure_storage. Ohne Konfiguration von secureStorage wird der Nachweis im selben Speicher wie der Gesprächsverlauf abgelegt. Ein eigener Button für den Live-Chat öffnet das Anfrageformular, wenn ein Mitarbeiter verfügbar ist. Andernfalls öffnet sich das Ticketformular mit der Erklärung:

import 'package:flutter_secure_storage/flutter_secure_storage.dart';

class SecureKavchatStorage implements KavchatStorage {
  final _s = const FlutterSecureStorage();
  @override
  Future<String?> read(String key) => _s.read(key: key);
  @override
  Future<void> write(String key, String value) => _s.write(key: key, value: value);
  @override
  Future<void> remove(String key) => _s.delete(key: key);
}

final kavchat = KavchatController(
  publicKey: 'pk_live_...',
  secureStorage: SecureKavchatStorage(),
  livePage: 'checkout',
  onLivePhase: (phase) => debugPrint('live chat: $phase'),
);

// your own button
FilledButton(onPressed: kavchat.openLive, child: const Text('Chat with us'));

Dieselbe Logik ohne Flutter finden Sie in kavchat_engine (KavchatClient, LiveSession und die gemeinsame Zustandsmaschine liveApplyEvent, liveLines und liveStatus, die dieselben Testvektoren wie das Website-Widget besteht).

Fragen, Bedingungen und Leads

In der App sind keine Einstellungen nötig. Ein Skript kann Angaben abfragen (Name, Telefonnummer, E-Mail-Adresse, Zahl oder Text), anhand von Bedingungen den weiteren Verlauf bestimmen (Premium) und einen Lead senden. Alles läuft auf dem Gerät.

• Passende Tastatur: Wenn der Bot auf eine Antwort wartet, erscheint für das Textfeld eine Telefon-, E-Mail- oder Zahlentastatur mit automatischer Vervollständigung. Ist die Antwort ungültig, erklärt der Bot, was fehlt, und das Feld wird markiert. Bei Fragen, die übersprungen werden können, erscheint der Button „Überspringen“.
• Lead: Wenn ein Einwilligungstext vorhanden ist, erscheinen die Buttons „Senden“ und „Nein, danke“. Ohne Netzwerkverbindung wird der Lead auf dem Gerät gespeichert und gesendet, sobald die Verbindung wiederhergestellt ist, ohne Duplikate.
• Vorausfüllen: Bereits gegebene Antworten werden in das Ticketformular und das Anfrageformular für den Live-Chat übernommen und dem Ticket sowie dem Gespräch mit dem Mitarbeiter beigefügt. Name, E-Mail-Adresse und Telefonnummer aus dem Identitätstoken gelten als bekannte Antworten. Der Bot fragt daher nicht erneut danach.
• Aktuelle Ansicht: livePage gibt auch die Ansicht an, die von Bedingungen geprüft und mit Leads gesendet wird. Rufen Sie setPage('checkout') auf, wenn der Nutzer zu einer anderen Ansicht wechselt.

KI-Antworten (Premium)

In Ihrer App müssen Sie nichts einrichten. Wenn Sie KI-Antworten im Dashboard 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 der kleinen Kennzeichnung „KI-Antwort“ in der Oberflächensprache. Darunter stehen, falls vorhanden, ein Button zu einem verwandten Thema sowie der Button „Team kontaktieren“.

Gibt es keine Antwort oder schlägt die Anfrage fehl, dauert zu lange oder überschreitet das Limit (10 Antworten pro Gespräch innerhalb von jeweils 15 Minuten), zeigt der Chat die übliche Meldung „Ich habe keine Antwort gefunden“. Die Frage erscheint weiterhin im Bericht zu unbeantworteten Fragen. KI-Antworten werden wie alle anderen Nachrichten im gespeicherten Gesprächsverlauf aufbewahrt.

Offline-Betrieb und Cache

Die Version wird mit ihrem ETag im Cache gespeichert (If-None-Match, 304). Ohne Netzwerkverbindung oder bei einem Serverfehler wird die gespeicherte Kopie verwendet und ein entsprechender Hinweis angezeigt. Der Gesprächsverlauf wird pro Bot gespeichert und 24 Stunden lang wiederhergestellt, solange sich die Version nicht geändert hat. Der Gesprächsablauf wird 2 Sekunden nach der letzten Aktion sowie beim Wechsel der App in den Hintergrund an den Server gemeldet.