Flutter SDK — EasyLiveChat-Dokumentation

§ 00Überblick

Das Flutter SDK spricht dasselbe anonyme Widget-Protokoll wie Ihr Website-Chat — so erreichen Kunden den Support aus Ihrer mobilen App heraus, und zwar in genau den Konversationen, die Ihre Agenten bereits im gemeinsamen Posteingang bearbeiten.

Es wird als zwei Pakete ausgeliefert:

easylivechat — Headless-Protokoll-Client mit reaktivem State, ohne UI
easylivechat_ui — vorgefertigte, gestaltbare Widgets — Launcher, Chat-Bildschirm, Pre-Chat-Formular, Anhänge, CSAT

§ 01Installation

Fügen Sie das SDK zur pubspec.yaml Ihrer App hinzu. Die meisten Apps benötigen easylivechat_ui — es re-exportiert den Core. Greifen Sie nur dann zum reinen Headless-easylivechat, wenn Sie eine vollständig individuelle UI bauen.

dependencies:
  easylivechat_ui: ^0.1.0   # prebuilt UI + the headless core
  # — or, headless only —
  easylivechat: ^0.1.0

Erfordert Flutter 3.19 oder neuer. socket_io_client muss ein 3.x-Release (Engine.IO v4) sein, um zum Server zu passen.

§ 02Schnellstart (sofort einsatzbereite UI)

Starten Sie den Client einmal mit Ihrem Workspace-Slug und fügen Sie dann einen Launcher in Ihren Widget-Baum ein. Die Blase öffnet einen vollständig verkabelten Chat: Pre-Chat-Formular, Echtzeit-Thread, Tippanzeige, Anhänge, CSAT, ein Offline-Formular für Geschäftszeiten sowie servergesteuertes Theming und RTL.

import 'package:easylivechat_ui/easylivechat_ui.dart';

await EasyLiveChat.instance.boot(
  const EasyLiveChatConfig(
    apiBase: 'https://api.livechattools.com',
    tenantSlug: 'acme',          // your workspace slug
  ),
  storage: SecurePrefsStorage(), // durable visitorId + JWT
);

// In your widget tree — a floating bubble that opens the full chat:
Stack(children: [ MyApp(), const EasyLiveChatLauncher() ]);

Ihren Workspace-Slug finden Sie in Ihrem Dashboard. Der Launcher startet beim ersten Öffnen verzögert; übergeben Sie einen dauerhaften Speicher, damit die Besucheridentität App-Neustarts übersteht.

§ 03Headless (eigene UI bauen)

Sie bevorzugen Ihr eigenes Designsystem? Steuern Sie den Headless-Client direkt. Alles wird als ValueListenables und Streams bereitgestellt, die Sie an jedes State-Management anbinden können.

import 'package:easylivechat/easylivechat.dart';

final chat = EasyLiveChat.instance;
await chat.boot(const EasyLiveChatConfig(
  apiBase: 'https://api.livechattools.com', tenantSlug: 'acme'),
  storage: myDurableStorage);  // implement EasyLiveChatStorage
await chat.open();             // config → resume → prechat/anon → connect

chat.messages.addListener(rebuild);    // ValueListenable<List<ChatMessage>>
chat.agentTyping.addListener(rebuild);

final res = chat.sendMessage('Hello!'); // optimistic; res.serverMessageId on ack
await chat.submitFeedback(rating: 5);

open() orchestriert den vollständigen Lebenszyklus: Konfiguration abrufen, eine offene Konversation fortsetzen, am Pre-Chat-Formular abfragen oder anonym starten und anschließend den Echtzeit-Socket verbinden.

§ 04Funktionsweise

Wenn eine Sitzung geöffnet wird, erzeugt der Server ein kurzlebiges, konversationsspezifisches Token. Das SDK verwendet es für die REST-Aufrufe und den Echtzeit-Socket, erneuert es transparent vor dem Ablauf und stellt bei einem Abbruch des Mobilfunknetzes die Verbindung mit einem lückensicheren Backfill wieder her.

Alles ist anonym-first: Das SDK erzeugt eine dauerhafte Besucher-ID auf dem Gerät — keine Anmeldung erforderlich — und erfasst optional Name und E-Mail über das Pre-Chat-Formular des Mandanten.

Sicherheit: Betten Sie niemals Ihren Mandanten-API-Schlüssel in eine ausgelieferte App ein — das ist ein Server-zu-Server-Geheimnis. Das Flutter SDK verwendet ausschließlich das besucherspezifische Sitzungstoken, das für einen verteilten Client sicher ist.

§ 05Was serverseitige Arbeit erfordert

Das vollständige Vordergrund-Chat-Erlebnis funktioniert heute ohne Backend-Änderungen. Die einzige Funktion, die Serverarbeit erfordert, ist Hintergrund-Push — das Zustellen einer „Agent hat geantwortet“-Benachrichtigung an eine geschlossene App — denn das Backend pusht derzeit nur an Agenten. Eine Besucher-Push-Registry und ein Fan-out sind erforderlich, um dies zu aktivieren; der Push-Hook des SDK bleibt bis dahin inaktiv.

Empfohlene Folgemaßnahmen vor einem öffentlichen Launch: Rate-Limiting bei der Sitzungserstellung und beim Nachrichtenversand, ein Endpunkt zur Token-Aktualisierung sowie Upload-Unterstützung für HEIC/MOV bei Smartphone-Medien.

Änderung vorschlagen