Kavchat by maxsave
Dokumentationsmenü

Android

Die Android-Bibliothek von Kavchat ergänzt Ihre App um den skriptbasierten Support-Bot, mit Jetpack-Compose-Komponenten und einer Activity für Apps mit Views. Die Antworten sind vorhersehbar und funktionieren auch offline auf Basis der zuletzt veröffentlichten Version. Erforderlich ist Android 6.0 (API 23) oder höher.

Es gibt zwei Komponenten: kavchat-engine, eine Kotlin/JVM-Version der Gesprächs-Engine ohne Abhängigkeiten von Android oder Drittanbieter-Bibliotheken, und kavchat mit Netzwerkanbindung (HttpURLConnection), lokalem Cache (SharedPreferences), den Compose-Komponenten KavchatChat und KavchatLauncher sowie KavchatActivity.

Installation

Gradle (Kotlin DSL)
// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://jitpack.io")
    }
}

// app/build.gradle.kts
dependencies {
    implementation("com.kavchat:kavchat-android:0.0.11")
}

Die Bibliothek wird über JitPack bereitgestellt. Fügen Sie dessen Repository daher einmalig neben google() und mavenCentral() hinzu. Das SDK ist Open Source und steht unter der MIT-Lizenz: bitbucket.org/maxsave/kavchat-android.

Die Bibliothek deklariert die Berechtigung INTERNET und KavchatActivity selbst in ihrem Manifest. Sie müssen nichts manuell ergänzen.

Einrichtung

Rufen Sie configure einmalig in Application.onCreate auf:

Kotlin
class App : Application() {
    override fun onCreate() {
        super.onCreate()
        Kavchat.configure(this, publicKey = "pk_live_...")
        // Optional: Kavchat.configure(this, "pk_live_...", apiBase = "https://api.kavchat.com", locale = "he")
    }
}

Der öffentliche Schlüssel darf in der App enthalten sein. Den geheimen Schlüssel (sk_live_...) dürfen Sie niemals in die App aufnehmen.

Compose

Ein schwebender Button in der im Dashboard gewählten Ecke öffnet den Chat im Vollbildmodus:

Compose
KavchatOverlay(Modifier.fillMaxSize()) {
    AppContent()
}

Sie können den Button auch selbst platzieren oder den Chat in eine eigene Ansicht einbetten:

Compose
KavchatLauncher()                                    // com.kavchat.ui.KavchatLauncher
KavchatChat(Modifier.fillMaxSize())                  // full chat, no close button
KavchatChat(Modifier.fillMaxSize(), onClose = { navController.popBackStack() })

Mit Kavchat.controller.setPresented(true) und setPresented(false) öffnen und schließen Sie den Chat des schwebenden Buttons per Code.

Views (ohne Compose in Ihrer App)

Kotlin
Kavchat.open(context)                                // starts KavchatActivity

Aus Java: Kavchat.open(context);. Die Activity verwendet intern Compose, Ihre App muss das aber nicht.

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.

Kotlin
Kavchat.setUser(token = identityToken, name = "Dana")   // after login
Kavchat.setUser(token = null)                           // after logout

Beim Nutzerwechsel wird die Version neu geladen und ein neues Gespräch begonnen. So wird das Gespräch eines Nutzers keinem anderen angezeigt.

App-Ansichten: onScreen

Ein Button vom Typ screen im Skript fordert die App auf, eine ihrer Ansichten zu öffnen. Zuerst wird der Chat geschlossen (der Dialog von KavchatLauncher oder KavchatActivity), damit die Ansicht sichtbar wird:

Kotlin
Kavchat.onScreen = { screen, targetId ->
    navController.navigate("$screen/${targetId.orEmpty()}")   // e.g. "orders", "42"
}

Ohne Handler haben diese Buttons keine Funktion. Buttons vom Typ link öffnen nur https-Links (im Browser) und tel-Links (in der Telefon-App). Für die Datenanalyse meldet Kavchat.onEvent die Ereignisse Ready, Unavailable, Open, Close, Effect und Ticket.

Liste der App-Ansichten im Editor

Deklarieren Sie einmalig in Kavchat.configure(..., screens = ...) die Ansichten, die Ihre App öffnen kann (Typ KavchatAppScreen). Das SDK sendet die Liste automatisch an Kavchat. Der Skripteditor bietet diese Ansichten dann mit ihren Namen in einer Auswahlliste statt in einem Freitextfeld an. Er fragt auch nach einer Element-ID, wenn eine Ansicht sie benötigt, und warnt bei Buttons, die auf eine nicht deklarierte Ansicht verweisen. Die Liste der Ansichten muss niemand manuell im Dashboard eingeben.

Kotlin
Kavchat.configure(
    this, publicKey = "pk_live_...",
    screens = listOf(
        KavchatAppScreen("orders", "My orders"),
        KavchatAppScreen("product", "Product page", needsTarget = true),   // needs a targetId
    ),
)
// or later: Kavchat.registerScreens(listOf(...))
  • id ist der Wert, den onScreen erhält: lateinische Buchstaben, Ziffern, _, . und -, bis zu 40 Zeichen. label ist der Name, den der Administrator sieht, bis zu 60 Zeichen. Maximal 100 Ansichten. Ungültige Einträge und doppelte IDs werden ausgelassen.
  • needsTarget: Der Button enthält zusätzlich eine Element-ID (zum Beispiel eine Produkt-ID), die onScreen als targetId erhält.
  • 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 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.

Farben

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

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.

Sprachen und RTL

  • Die Sprache der Oberfläche richtet sich nach dem an configure übergebenen locale. Wurde keines übergeben, wird die Gerätesprache verwendet, sofern eine Übersetzung vorliegt (he, en, ar, ru, es, fr, de, pt, it, tr). Danach folgt die Skriptsprache, 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 LocalLayoutDirection für den gesamten Chat auf RTL gesetzt. Nichts wird manuell gespiegelt: Wenn Sie die Komponenten in eigene Container einbetten, verwenden Sie start und end. Behalten Sie android:supportsRtl="true" im Manifest Ihrer App bei.

KI-Antworten (Premium)

In der App ist keine Einrichtung nötig. Wenn Sie KI-Antworten in der Verwaltungsoberfläche 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 einfacher Text mit dem kleinen Hinweis „KI-Antwort“ in der Sprache der Oberfläche. Darunter stehen ein Button zu einem verwandten Thema, sofern vorhanden, und der Button „Team kontaktieren“.

Wenn keine Antwort vorliegt oder 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 alle anderen Nachrichten im gespeicherten Gespräch aufbewahrt.

Chat mit einem Mitarbeiter

In der App ist keine Einrichtung nötig. Wenn Sie den Chat mit Mitarbeitern in der Verwaltungsoberfläche aktivieren, funktioniert der Chat in der App genauso wie das Widget auf der Website.

  • Die Option erscheint nur, wenn der Chat mit Mitarbeitern 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 für 30 Sekunden zwischengespeichert. Ist jemand verfügbar, erscheint davor der Button „Mit einem Mitarbeiter chatten“. Andernfalls wird nur das Kontaktformular angezeigt. Darüber erklärt eine kurze Zeile den Grund: außerhalb der Geschäftszeiten (einschließlich 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 erste Nachricht (optional). Gäste müssen eine E-Mail-Adresse oder Telefonnummer hinterlassen. Nutzer, die über ein Identitätstoken identifiziert wurden, müssen beides nicht angeben. 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 der Button „Stattdessen Nachricht hinterlassen“ angezeigt. Die Wartezeit wird in der Verwaltungsoberfläche festgelegt und beträgt standardmäßig 2 Minuten. Auch während des Wartens können Nachrichten geschrieben werden, die der Mitarbeiter dann sieht. 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 ein Button zum Beenden des Gesprächs angezeigt. Nachrichten enthalten ausschließlich einfachen Text mit bis zu 2.000 Zeichen, ohne Links. Eine Nachricht, die den Server noch nicht erreicht hat, wird mit „Wird gesendet...“ gekennzeichnet. Schlägt der Versand mehrfach fehl, lässt er sich durch Antippen der Nachricht erneut versuchen. Dabei entsteht keine doppelte Nachricht.
  • Nach jedem Verbindungsabbruch wartet das SDK kurz, lädt verpasste Inhalte nach und stellt die Verbindung wieder her. Die Wartezeit steigt dabei schrittweise. Nachrichten werden immer in der richtigen Reihenfolge und ohne Duplikate angezeigt. Funktioniert die dauerhafte Verbindung nicht (zum Beispiel hinter einem Unternehmensproxy), wechselt das SDK vorübergehend zu wiederholten Serverabfragen.
  • Wenn die App in den Hintergrund wechselt, wird die Verbindung geschlossen. Bei der Rückkehr lädt das SDK verpasste Inhalte nach und stellt die Verbindung wieder her. Ein laufendes Gespräch wird auch nach dem Schließen und erneuten Starten der App fortgesetzt, sofern noch keine 12 Stunden vergangen sind.
  • In dieser Version gibt es keine Push-Benachrichtigungen. Nachrichten kommen nur an, wenn 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 im Arbeitsspeicher gehalten. Auf dem Gerät werden sie nur verschlüsselt mit einem Schlüssel aus dem Android Keystore gespeichert. Sie werden weder in eine URL noch in ein Protokoll geschrieben. Die Daten werden gelöscht, wenn das Gespräch endet, in ein Ticket umgewandelt wird oder abläuft, sowie beim Nutzerwechsel über setUser.

Mit Kavchat.controller.livePage können Sie dem Mitarbeiter mitteilen, aus welcher Ansicht der Nutzer kommt.

Fragen, Bedingungen und Leads

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

  • Passende Tastatur: Wenn der Bot auf eine Antwort wartet, zeigt das Textfeld eine Telefon-, E-Mail- oder Zahlentastatur an. Bei einer Namensfrage wird der erste Buchstabe jedes Wortes großgeschrieben. Ist die Antwort ungültig, reagiert der Bot mit einer kurzen Meldung in der Chatsprache und das Feld wird markiert. Bei einer überspringbaren Frage erscheint der Button „Ü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 der Verwaltungsoberfläche festgelegt ist.
  • Lead: Ein Lead-Schritt zeigt den Zustimmungstext mit den Buttons „Senden“ und „Nein, danke“ an, anschließend die Bestätigungsnachricht. 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 zur Anfrage eines Mitarbeiter-Chats werden mit dem erfassten Namen, der E-Mail-Adresse und der Telefonnummer vorausgefüllt. Alle erfassten Werte werden dem Ticket oder der Chat-Anfrage beigefügt. Fragen vor einem Mitarbeiter-Chat (Premium) werden vor dem Verbindungsaufbau gestellt.
  • Identitätstoken: Bei Verwendung von setUser füllen die Felder name, email und phone im Token die Antworten auf die passenden Fragen aus. Der Bot überspringt diese Fragen dann.
  • Aktuelle Ansicht: Bedingungen können die aktuelle Ansicht prüfen. Setzen Sie dafür Kavchat.controller.livePage (zum Beispiel "checkout").

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

Offline-Nutzung und Cache

Die letzte Version wird mit ihrem ETag in SharedPreferences 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 ausgeschaltet, nur für Testnutzer freigegeben oder das Kontingent aufgebraucht, wird nichts angezeigt. Ein laufendes Gespräch bleibt bei Inaktivität bis zu 30 Minuten erhalten. Das Verlassen des Chats oder der App startet es daher nicht neu. Der Gesprächsverlauf wird zwei Sekunden nach der letzten Aktion gemeldet sowie sofort, wenn die App in den Hintergrund wechselt.