React Native

Das Paket @kavchat/react-native ergänzt Ihre App um den skriptgesteuerten Support-Chat: mit Provider, Chat-Ansicht und optionalem schwebendem Chat-Button. Die Antworten stammen aus den Skripten, die Sie im Dashboard veröffentlicht haben. Die Skripte werden auf dem Gerät ausgeführt.

Installation

Das Paket ist vollständig in JavaScript geschrieben, ohne eigenen nativen Code und ohne Symbolbibliothek. Es funktioniert daher in einer regulären React Native-App genauso wie in Expo. Peer-Abhängigkeiten: react ab Version 18 und react-native ab Version 0.72.

React Native CLI (ohne Expo)

yarn add @kavchat/react-native @react-native-async-storage/async-storage
cd ios && pod install

AsyncStorage ist ein natives Modul: pod install bindet es unter iOS ein, unter Android erfolgt die Einbindung automatisch.

Expo

Das Paket funktioniert in Expo Go und in Entwicklungs-Builds:

yarn add @kavchat/react-native
npx expo install @react-native-async-storage/async-storage

Ohne AsyncStorage

AsyncStorage speichert die veröffentlichte Version und das Gespräch über App-Starts hinweg. Die Installation ist optional: Ohne AsyncStorage hält das Paket alles im Arbeitsspeicher. Der Bot funktioniert weiterhin, lädt die Version aber bei jedem Start erneut herunter. Für einen anderen Speicher, etwa MMKV, übergeben Sie der Prop storage ein beliebiges synchrones oder asynchrones Objekt { getItem, setItem, removeItem? }:

import { MMKV } from 'react-native-mmkv';
const mmkv = new MMKV();
const storage = {
  getItem: (k: string) => mmkv.getString(k) ?? null,
  setItem: (k: string, v: string) => mmkv.set(k, v),
  removeItem: (k: string) => mmkv.delete(k),
};

<KavchatProvider publicKey="pk_live_..." storage={storage}>

Verwendung

import { KavchatProvider, KavchatChat, KavchatLauncher, useKavchat } from '@kavchat/react-native';

export default function App() {
  return (
    <KavchatProvider publicKey="pk_live_..." onScreen={(screen, id) => navigation.navigate(screen, { id })}>
      <Navigation />
      {/* floating button, bottom end corner; opens the chat in a modal */}
      <KavchatLauncher />
    </KavchatProvider>
  );
}

// or as a screen in your own navigator
function SupportScreen() {
  return <KavchatChat />;
}

// or your own button
function HelpButton() {
  const { available, open } = useKavchat();
  if (!available) return null; // bot is off, limited to testers, or over quota
  return <Button title="Help" onPress={open} />;
}

Props von KavchatProvider

useKavchat() gibt { status, available, offline, locale, isOpen, open, close, toggle, setUser, startNewConversation, openContactForm, controller } zurück.

Props von KavchatChat: onClose? (zeigt einen Schließen-Button), hideHeader? und style?. Props von KavchatLauncher: style? (Position), onPress? (öffnet Ihren eigenen Bildschirm statt des integrierten Fensters) und attention? (false deaktiviert den Hinweis).

Wenn im Dashboard ein Hinweis neben dem Chat-Button eingerichtet ist (eine Sprechblase oder gebogener Text über dem Button), zeigt KavchatLauncher ihn nach der eingestellten Verzögerung an, höchstens einmal pro Tag. Wird der Hinweis geschlossen oder der Chat geöffnet, bleibt er bis zum nächsten Tag ausgeblendet. Bei geöffnetem Chat wird er nicht angezeigt. Ist auf dem Gerät die Option zur Reduzierung von Bewegung aktiviert, erscheint der Hinweis ohne Animation. Mit der Option „Nicht auf Smartphones anzeigen“ erscheint er nur auf Tablets (wenn die kürzere Bildschirmseite mindestens 600 Punkte misst).

Identitätstoken

Ohne Token gilt der Benutzer als Gast, und das Kontaktformular fragt nach E-Mail-Adresse oder Telefonnummer. Um einen angemeldeten Benutzer zu identifizieren, signieren Sie ein kurzlebiges JWT auf Ihrem Server mit dem geheimen Schlüssel (niemals in der App, siehe Benutzer identifizieren) und übergeben es so:

<KavchatProvider publicKey="pk_live_..." userToken={session?.kavchatToken} userName={session?.firstName}>

Eine Änderung von userToken (An- oder Abmeldung) lädt die Version neu, da die Zugehörigkeit zu den Testbenutzern von der Benutzeridentität abhängt. Sie können auch useKavchat().setUser({ token, name }) aufrufen. Das Token wird nur im Header Authorization: Bearer gesendet und nicht auf dem Gerät gespeichert. Ein gespeichertes Gespräch ist an einen Fingerabdruck des Tokens gebunden. Ein anderer Benutzer auf demselben Gerät beginnt daher ein neues Gespräch.

Links, Bildschirme und Kontaktformular

• Buttons vom Typ link öffnen über Linking.openURL nur URLs mit https: und tel:. Andere URL-Schemata werden nicht geöffnet.
• Buttons vom Typ screen rufen onScreen auf. Der Chat bleibt an der bisherigen Stelle.
• Der Button „Team kontaktieren“ öffnet das Kontaktformular mit dem angehängten Gespräch. Nach dem Absenden wird die Ticketnummer angezeigt.

Bildschirmliste im Editor

Deklarieren Sie die Bildschirme, die Ihre App öffnen kann, einmal in der Prop screens von KavchatProvider. 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. Er fragt auch nach einer Element-ID, wenn ein Bildschirm sie benötigt, und warnt bei Buttons, die auf einen nicht deklarierten Bildschirm verweisen. Die Bildschirmliste muss niemand manuell im Dashboard eingeben.

const screens = [
  { id: 'orders', label: 'My orders' },
  { id: 'product', label: 'Product page', needsTarget: true }, // the button also carries a product id
];

<KavchatProvider
  publicKey="pk_live_..."
  screens={screens}
  onScreen={(screen, targetId) => navigation.navigate(screen, targetId ? { id: targetId } : undefined)}
>

• 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 ausgelassen.
• needsTarget: Der Button enthält zusätzlich eine Element-ID (etwa 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. Fehler bleiben unbemerkt; beim nächsten Start wird der Versand erneut versucht. Der Benutzer sieht davon nichts.
• Die registrierten Bildschirme erscheinen im Dashboard unter Bot, Einstellungen, „App-Bildschirme“, zusammen mit den Plattformen, die den jeweiligen Bildschirm gemeldet haben. Aus der App entfernte Bildschirme können Sie dort löschen.

Farben und RTL

Die Farben stammen aus den Bot-Einstellungen im Dashboard (primaryColor). Die darauf angezeigte Textfarbe wird anhand des WCAG-Kontrasts gewählt. Sie können jede dieser Farben überschreiben: primary, background, botBubble, userBubble, text, muted, accent, onPrimary und error:

<KavchatProvider
  publicKey="pk_live_..."
  theme={{ primary: '#0f766e', background: '#ffffff' }}
>

Das Paket ändert die Layoutrichtung Ihrer App nicht. Es richtet sich nach I18nManager.isRTL (start- und end-Stile). Jeder Text wird entsprechend seiner Sprache ausgerichtet, sodass Hebräisch und Arabisch auch in einer von links nach rechts ausgerichteten App korrekt lesbar sind. Ist Ihre App auf Hebräisch oder Arabisch, richten Sie RTL wie gewohnt einmal in der App ein: I18nManager.forceRTL(true) und ein Neustart.

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 Start ist keine Einrichtung nötig. Sobald Sie den Live-Chat im Dashboard aktivieren, erscheint die Option im App-Chat genauso wie im Website-Widget.

• Die Option: „Mit einem Mitarbeiter chatten“ erscheint vor „Team kontaktieren“, und zwar erst, wenn 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 Kontaktformular angezeigt, mit einer kurzen Erklärung und, falls bekannt, dem Zeitpunkt, ab 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 für den Fall, dass niemand rechtzeitig verfügbar ist. Sie können auch einen Namen und eine erste Nachricht ergänzen. Sind mehrere Abteilungen geöffnet, wählen sie eine aus. Identifizierte Benutzer (userToken) müssen keine Kontaktdaten eingeben. Kann kein Mitarbeiter das Gespräch übernehmen, öffnet sich das Kontaktformular 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“. Benutzer können schon während des Wartens schreiben. Nach Ablauf der Wartezeit wird das Gespräch automatisch in ein Ticket umgewandelt. Angezeigt werden die Ticketnummer und der Hinweis, dass kein Mitarbeiter rechtzeitig verfügbar war.
• Das Gespräch: Name des Mitarbeiters, Nachrichten, Tippanzeige, Übergabe an einen anderen Mitarbeiter und Beenden des Gesprächs. Alles, was vom Server kommt, wird als reiner Text ohne Links angezeigt.
• In Echtzeit: Eine Server-Sent Events-Verbindung über XMLHttpRequest (oder Fetch-Streaming, wo verfügbar). Bricht die Verbindung ab, verbindet sich der Chat in zunehmend größeren Abständen erneut und lädt alles Verpasste nach. So geht keine Nachricht verloren und keine erscheint doppelt. In Netzwerken, die diese Verbindung blockieren, wechselt der Chat zu wiederholten Abfragen (Long-Polling). Jede Nachricht hat eine ID, sodass ein erneuter Versuch kein Duplikat erzeugt. Nicht gesendete Nachrichten werden markiert und können durch Antippen erneut gesendet werden.
• Hintergrund und Neustart: Wechselt die App in den Hintergrund, wird die Verbindung geschlossen. Sobald sie zurückkehrt, lädt der Chat alles Verpasste nach. Die Zugangsberechtigung für das Gespräch gilt bis zu 12 Stunden oder bis zum Gesprächsende und wird im von Ihnen gewählten Speicher abgelegt. So erscheint ein laufendes Gespräch nach einem App-Neustart wieder auf dem Bildschirm. Die Berechtigung wird weder in einer URL gespeichert noch in ein Log geschrieben.
• Keine Push-Benachrichtigungen in dieser Version: Nachrichten des Mitarbeiters kommen nur an, während die App geöffnet ist.

Wir empfehlen, die Zugangsberechtigung in einem sicheren Speicher abzulegen (Keychain unter iOS, Keystore unter Android). Wenn Sie secureStorage nicht konfigurieren, wird sie im selben Speicher wie das Gespräch abgelegt. Ein eigener Button für den Live-Chat öffnet das Anfrageformular, wenn ein Mitarbeiter verfügbar ist. Andernfalls öffnet sich das Kontaktformular mit der Erklärung:

import * as SecureStore from 'expo-secure-store';

// expo-secure-store allows only [A-Za-z0-9._-] in keys
const safe = (k: string) => k.replace(/[^A-Za-z0-9._-]/g, '_');
const secureStorage = {
  getItem: (k: string) => SecureStore.getItemAsync(safe(k)),
  setItem: (k: string, v: string) => SecureStore.setItemAsync(safe(k), v),
  removeItem: (k: string) => SecureStore.deleteItemAsync(safe(k)),
};

<KavchatProvider publicKey="pk_live_..." secureStorage={secureStorage} livePage="checkout">

// your own button
const { openLive } = useKavchat();
<Button title="Chat with us" onPress={openLive} />

Ereignisse: onEvent erhält { type: 'live', phase } bei jeder Statusänderung des Gesprächs (queued, active, closed, ticket, replaced, expired).

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 Ablauf bestimmen (Premium) und einen Lead senden. Alles läuft auf dem Gerät.

• Passende Tastatur: Wenn der Bot auf eine Antwort wartet, öffnet das Textfeld eine Telefon-, E-Mail- oder Zahlentastatur mit Autovervollständigung. Ist die Antwort ungültig, erklärt der Bot, was fehlt, und das Feld wird markiert. Bei überspringbaren Fragen erscheint der Button „Überspringen“.
• Lead: Ist ein Einwilligungstext vorhanden, 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 füllen das Kontaktformular und das Anfrageformular für den Live-Chat aus. Sie werden dem Ticket und dem Gespräch mit dem Mitarbeiter beigefügt. Name, E-Mail-Adresse und Telefonnummer aus dem Identitätstoken gelten als bekannte Antworten, sodass der Bot nicht erneut danach fragt.
• Aktueller Bildschirm: livePage gibt auch den Bildschirm an, den die Bedingungen prüfen und der mit Leads gesendet wird. Eine Änderung der Prop aktualisiert ihn.

KI-Antworten (Premium)

In der 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 tippt. Die Antwort erscheint als reiner Text mit der kleinen Kennzeichnung „KI-Antwort“ in der Sprache der Oberfläche. Darunter stehen ein Button zu einem verwandten Thema, falls vorhanden, und der Button „Team kontaktieren“.

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

Verhalten

• Die veröffentlichte Version wird mit ihrem ETag zwischengespeichert (If-None-Match, 304). Ohne Netzwerkverbindung wird die gespeicherte Version mit einem entsprechenden Hinweis angezeigt.
• Das Gespräch wird auf dem Gerät gespeichert und 24 Stunden lang wiederhergestellt, solange Version und Benutzer unverändert bleiben.
• Der Gesprächsverlauf wird 2 Sekunden nach der letzten Aktion sowie beim Wechsel der App in den Hintergrund gemeldet.
• Die Anfragen senden keine benutzerdefinierten Header, nur Authorization, Content-Type und If-None-Match.