Kavchat by maxsave
Dokumentationsmenü

iOS

Das Swift-Paket von Kavchat ergänzt Ihre iOS-App um den skriptbasierten Support-Bot mit SwiftUI- und UIKit-Komponenten. Die Antworten sind vorhersehbar und funktionieren auch offline auf Basis der zuletzt veröffentlichten Version. Erfordert iOS 15 oder neuer.

Das Paket enthält zwei Produkte: KavchatEngine, die Swift-Version der Gesprächs-Engine ohne UIKit, und Kavchat mit Netzwerkanbindung, lokalem Cache und Benutzeroberfläche: KavchatChatView (SwiftUI), KavchatLauncher und KavchatViewController (UIKit).

Installation

Mit Swift Package Manager in Xcode: Wählen Sie Datei > Paketabhängigkeiten hinzufügen und geben Sie die Repository-URL ein:

Package URL
https://bitbucket.org/maxsave/kavchat-ios.git

Oder in der Datei Package.swift:

Package.swift
.package(url: "https://bitbucket.org/maxsave/kavchat-ios.git", from: "0.0.11"),
// ...
.product(name: "Kavchat", package: "kavchat-ios"),

Das SDK ist Open Source unter der MIT-Lizenz: bitbucket.org/maxsave/kavchat-ios.

Einrichtung

Rufen Sie configure einmal möglichst früh auf, zum Beispiel im init Ihrer App oder in application(_:didFinishLaunchingWithOptions:):

Swift
import Kavchat

Kavchat.configure(publicKey: "pk_live_...")            // the public key from the dashboard
// Optional:
// Kavchat.configure(publicKey: "pk_live_...", apiBase: "https://api.kavchat.com", locale: "he")

Den öffentlichen Schlüssel dürfen Sie in die App einbinden. Den geheimen Schlüssel (sk_live_...) dürfen Sie niemals in die App einbinden.

SwiftUI

Eine schwebende Schaltfläche in der im Dashboard gewählten Ecke, die den Chat in einem Fenster (Sheet) öffnet:

SwiftUI
ContentView()
    .kavchatLauncher()

Sie können die Schaltfläche auch selbst platzieren oder den Chat in einen eigenen Bildschirm einbetten:

SwiftUI
KavchatLauncher()
KavchatChatView()                                      // full chat, no close button
KavchatChatView(onClose: { showChat = false })         // with a close button

Mit Kavchat.open() und Kavchat.close() öffnen und schließen Sie das Fenster der schwebenden Schaltfläche per Code.

UIKit

UIKit
Kavchat.present(from: self)                            // modal, with a close button
// or
let chat = KavchatViewController(showsCloseButton: false)
navigationController?.pushViewController(chat, animated: true)

Identitätstoken

Identifizieren Sie angemeldete Nutzer mit einem JWT, das Ihr Server mit dem geheimen Schlüssel signiert (siehe Nutzer identifizieren). Das Token wird im Header Authorization: Bearer <token> gesendet. Identifizierte Nutzer können Versionen sehen, die nur für Testnutzer freigegeben sind, und das Kontaktformular ohne E-Mail-Adresse oder Telefonnummer absenden.

Swift
Kavchat.setUser(token: identityToken, name: "Dana")    // after login
Kavchat.setUser(token: nil)                            // after logout

Bei einem Nutzerwechsel wird die Version neu geladen und ein neues Gespräch gestartet. So erscheint das Gespräch eines Nutzers nicht bei einem anderen.

App-Bildschirme: onScreen

Eine Schaltfläche vom Typ screen im Skript fordert die App auf, einen ihrer Bildschirme zu öffnen. Das Chatfenster wird vorher geschlossen, damit der Bildschirm sichtbar ist:

Swift
Kavchat.onScreen = { screen, targetId in
    router.open(screen, id: targetId)                  // e.g. "orders", "42"
}

Ohne Handler haben diese Schaltflächen keine Funktion. Schaltflächen vom Typ link öffnen nur https- und tel-Links. Für die Datenanalyse meldet Kavchat.onEvent die Ereignisse ready, unavailable, open, close, effect und ticket.

Bildschirmliste im Editor

Deklarieren Sie einmal in Kavchat.configure(..., screens:), welche Bildschirme die App öffnen kann. Das SDK sendet die Liste selbstständig an Kavchat. Der Skripteditor bietet diese Bildschirme dann mit ihren Namen in einer Auswahlliste statt in einem Freitextfeld an. Wenn ein Bildschirm eine Element-ID benötigt, fragt der Editor danach. Er warnt auch bei Schaltflächen, die auf einen nicht deklarierten Bildschirm verweisen. Die Bildschirmliste muss niemand manuell im Dashboard eingeben.

Swift
Kavchat.configure(publicKey: "pk_live_...", screens: [
    KavchatScreen(id: "orders", label: "My orders"),
    KavchatScreen(id: "product", label: "Product page", needsTarget: true),  // needs a targetId
])
// or later: 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. Maximal 100 Bildschirme. Ungültige Einträge und doppelte IDs werden weggelassen.
  • needsTarget: Die Schaltfläche 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. Ein Fehler bleibt unbemerkt; beim nächsten Start wird der Versand erneut versucht. Für den Nutzer ist nichts davon sichtbar.
  • Die registrierten Bildschirme erscheinen im Dashboard unter Bot, Einstellungen, „App-Bildschirme“, zusammen mit den Plattformen, die den jeweiligen Bildschirm gemeldet haben. Einen aus der App entfernten Bildschirm können Sie dort löschen.

Farben

Die Farben werden aus dem Dashboard übernommen (primaryColor). Text auf der Markenfarbe wird je nach WCAG-Kontrast weiß oder nahezu schwarz dargestellt. Ist eine Farbe für Text auf weißem Hintergrund zu hell, wird sie bei Links und Schaltflächen durch nahezu Schwarz ersetzt. Auch Bot-Name, Untertitel, Bild und die Seite der schwebenden Schaltfläche (start oder end) stammen aus dem Dashboard und lassen sich daher ohne App-Update ändern.

Der Hinweis „Betrieben mit 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.

Sprachen und RTL

  • Die Sprache der Benutzeroberfläche richtet sich nach dem an configure übergebenen locale. Fehlt dieser Wert, wird die Gerätesprache verwendet, sofern eine Übersetzung vorhanden ist (he, en, ar, ru, es, fr, de, pt, it, tr). Danach folgt die Skriptsprache und zuletzt Englisch.
  • Der Abgleich mit dem Skript erfolgt immer in der Skriptsprache (häufige Wörter, die übersprungen werden, sowie hebräische und arabische Präfixe).
  • Bei Hebräisch und Arabisch ist layoutDirection für den gesamten Chat auf rechts nach links gesetzt. Nichts wird manuell gespiegelt: Wenn Sie die Komponenten in eigene Container einbetten, verwenden Sie leading und trailing.

KI-Antworten (Premium)

In der App müssen Sie nichts konfigurieren. 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 Klartext mit der kleinen Kennzeichnung „KI-Antwort“ in der Sprache der Benutzeroberfläche. Darunter stehen eine Schaltfläche zu einem verwandten Thema, sofern vorhanden, und die Schaltfläche „Team kontaktieren“.

Wenn keine Antwort vorliegt, die Anfrage fehlschlägt, zu lange dauert oder das Limit überschreitet (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 jede andere Nachricht im gespeicherten Gespräch aufbewahrt.

Chat mit einem Mitarbeiter

In der App müssen Sie nichts konfigurieren. Wenn Sie den Mitarbeiter-Chat im Verwaltungsbereich aktivieren, funktioniert der Chat in der App genauso wie das Widget auf der Website.

  • Die Option wird nur angezeigt, wenn der Mitarbeiter-Chat in der veröffentlichten Version aktiviert ist. Sobald der Bot „Team kontaktieren“ anzeigt, prüft das SDK, ob ein Mitarbeiter verfügbar ist. Das Ergebnis wird 30 Sekunden lang zwischengespeichert. Ist ein Mitarbeiter verfügbar, erscheint davor die Schaltfläche „Mit Mitarbeiter chatten“. Andernfalls wird nur das Kontaktformular angezeigt. Eine kurze Zeile darüber erklärt den Grund: außerhalb der Geschäftszeiten (mit der Uhrzeit, ab der das Team wieder erreichbar ist) oder alle Mitarbeiter sind beschäftigt.
  • Vor dem Gespräch wird ein kurzes Formular ausgefüllt: Name, E-Mail-Adresse oder Telefonnummer, Abteilung (nur wenn mehr als eine Abteilung geöffnet ist) und eine optionale erste Nachricht. Gäste müssen eine E-Mail-Adresse oder Telefonnummer hinterlassen. Für Nutzer, die per Identitätstoken identifiziert wurden, ist beides nicht erforderlich. Ist beim Absenden kein Mitarbeiter mehr verfügbar, öffnet sich das Kontaktformular mit den bereits eingegebenen Daten.
  • Während der Wartezeit werden die verbleibende Zeit bis zur Umwandlung des Gesprächs in ein Ticket und die Schaltfläche „Stattdessen Nachricht hinterlassen“ angezeigt. Die Wartezeit wird im Verwaltungsbereich festgelegt und beträgt standardmäßig 2 Minuten. Nutzer können auch während der Wartezeit schreiben; der Mitarbeiter sieht diese Nachrichten. Wird rechtzeitig kein Mitarbeiter frei, wird das Gespräch als reguläres Ticket gespeichert und die Ticketnummer angezeigt.
  • Während des Gesprächs werden der Name des Mitarbeiters, eine Meldung beim Beitritt eines Mitarbeiters (auch nach einer Übergabe), eine Schreibanzeige und eine Schaltfläche zum Beenden des Gesprächs angezeigt. Nachrichten enthalten nur Klartext mit bis zu 2.000 Zeichen, ohne Links. Eine Nachricht, die den Server noch nicht erreicht hat, ist mit „Wird gesendet...“ gekennzeichnet. Nach mehreren fehlgeschlagenen Sendeversuchen lässt sich die Nachricht antippen, um es erneut zu versuchen. Dabei entsteht keine doppelte Nachricht.
  • Nach jedem Verbindungsabbruch wartet das SDK kurz, lädt verpasste Inhalte nach und verbindet sich erneut. Die Wartezeit verlängert sich schrittweise. Nachrichten werden immer in der richtigen Reihenfolge und ohne Duplikate angezeigt. Kommt keine dauerhafte Verbindung zustande (zum Beispiel hinter einem Unternehmensproxy), fragt das SDK den Server vorübergehend in regelmäßigen Abständen ab.
  • Wenn die App in den Hintergrund wechselt, wird die Verbindung geschlossen. Bei der Rückkehr zur App lädt das SDK verpasste Inhalte nach und verbindet sich erneut. Ein offenes Gespräch wird auch nach dem Schließen und erneuten Starten der App fortgesetzt, solange noch keine 12 Stunden vergangen sind.
  • Diese Version unterstützt keine Push-Benachrichtigungen. Nachrichten kommen nur an, solange die App geöffnet ist. Eine Antwort, die gesendet wurde, während die App im Hintergrund war, erscheint sofort bei der Rückkehr zur App.
  • Die Zugangsdaten zum Gespräch werden nur im Arbeitsspeicher und in der Keychain des Geräts gespeichert. Sie werden weder in UserDefaults noch in einer URL oder einem Protokoll gespeichert. Die Daten werden gelöscht, wenn das Gespräch endet, in ein Ticket umgewandelt wird oder abläuft, sowie bei einem Nutzerwechsel über setUser.

Mit Kavchat.shared.livePage können Sie dem Mitarbeiter mitteilen, von welchem Bildschirm der Nutzer kommt.

Fragen, Bedingungen und Leads

In der App ist keine Konfiguration nötig. Ein Skript kann Angaben abfragen (Name, Telefonnummer, E-Mail-Adresse, Zahl oder Freitext), anhand bekannter Informationen den weiteren Ablauf bestimmen und einen Lead senden.

  • Passende Tastatur: Wenn der Bot auf eine Antwort wartet, erscheint für das Textfeld eine Telefon-, E-Mail- oder Zahlentastatur. Bei Namensfragen wird der erste Buchstabe jedes Wortes großgeschrieben. Ist die Antwort ungültig, reagiert der Bot mit einer kurzen Meldung in der Chatsprache und markiert das Feld. Bei überspringbaren Fragen erscheint die Schaltfläche „Überspringen“. Die Eingabe von „Abbrechen“ in einer beliebigen unterstützten Sprache beendet die Frage.
  • Telefon: Einer Nummer ohne + wird das Standardland des Arbeitsbereichs zugeordnet, das in den Einstellungen im Verwaltungsbereich festgelegt ist.
  • Lead: Ein Lead-Schritt zeigt den Einwilligungstext mit den Schaltflächen „Senden“ und „Nein, danke“, danach die Bestätigungsmeldung. Der Lead wird auf dem Gerät in eine Warteschlange aufgenommen und an den Server gesendet. Ohne Netzwerkverbindung oder bei nicht verfügbarem Server wird der Versand erneut versucht, auch beim nächsten Start und nach reload(). Der Server ignoriert Duplikate.
  • Vorausfüllen: Das Kontaktformular und das Formular für die Anfrage an einen Mitarbeiter werden mit dem erfassten Namen, der E-Mail-Adresse und der Telefonnummer vorausgefüllt. Alle erfassten Werte werden dem Ticket oder der Anfrage an einen Mitarbeiter beigefügt. Fragen vor einem Mitarbeiter-Chat (Premium) werden vor dem Verbindungsaufbau gestellt.
  • Identitätstoken: Bei Verwendung von setUser füllen die Token-Felder name, email und phone die Antworten auf die entsprechenden Fragen aus. Der Bot überspringt diese Fragen.
  • Aktueller Bildschirm: Bedingungen können den aktuellen Bildschirm prüfen. Setzen Sie dafür Kavchat.shared.livePage (zum Beispiel "checkout").

Die erfassten Werte sind personenbezogene Daten. Sie verbleiben im auf dem Gerät gespeicherten Gespräch und werden nur für Leads, Tickets und Mitarbeiter-Chats übertragen, niemals für Berichte.

Offline-Betrieb und Cache

Die letzte Version wird mit ihrem ETag in UserDefaults gespeichert und bei jedem Start mit If-None-Match (304) erneut geprüft. Ohne Netzwerkverbindung wird die gespeicherte Kopie verwendet und ein entsprechender Hinweis angezeigt. Ist der Bot deaktiviert, nur für Testnutzer freigegeben oder das Kontingent aufgebraucht, wird nichts angezeigt. Ein offenes Gespräch bleibt bis zu 30 Minuten ohne Aktivität gespeichert, sodass es beim Verlassen des Chats oder der App nicht neu beginnt. Der Gesprächsverlauf wird zwei Sekunden nach der letzten Aktion gemeldet und sofort, wenn die App in den Hintergrund wechselt.