Supporto live, dentro
la tua app Flutter

§ 00Panoramica

Il Flutter SDK parla lo stesso protocollo del widget anonimo usato dalla chat del tuo sito web, così i clienti possono raggiungere il supporto dall'interno della tua app mobile, sulle stesse conversazioni che i tuoi agenti già gestiscono nella casella di posta condivisa.

Viene distribuito come due pacchetti:

• easylivechat — client di protocollo headless più stato reattivo, senza interfaccia
• easylivechat_ui — widget predefiniti e personalizzabili tramite tema: launcher, schermata di chat, modulo pre-chat, allegati, CSAT

§ 01Installazione

Aggiungi l'SDK al file pubspec.yaml della tua app. La maggior parte delle app vuole easylivechat_ui, che riesporta il core. Ricorri al solo easylivechat headless unicamente quando stai costruendo un'interfaccia completamente personalizzata.

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

Richiede Flutter 3.19 o versione successiva. socket_io_client deve essere una release 3.x (Engine.IO v4) per essere compatibile con il server.

§ 02Avvio rapido (interfaccia pronta all'uso)

Avvia il client una volta con lo slug del tuo workspace, poi inserisci un launcher nel tuo albero di widget. La bolla apre una chat completamente cablata: modulo pre-chat, conversazione in tempo reale, indicatore di digitazione, allegati, CSAT, un modulo offline per gli orari di lavoro, oltre alla personalizzazione del tema guidata dal server e all'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() ]);

Trovi lo slug del tuo workspace nella tua dashboard. Il launcher si avvia in modalità lazy alla prima apertura; fornisci uno storage durevole affinché l'identità del visitatore sopravviva ai riavvii dell'app.

§ 03Headless (costruisci la tua interfaccia)

Preferisci il tuo design system? Pilota direttamente il client headless. Tutto è esposto come ValueListenables e Streams che puoi collegare a qualsiasi gestione dello stato.

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() orchestra l'intero ciclo di vita: recupera la configurazione, riprende qualsiasi conversazione aperta, applica il gate del modulo pre-chat o avvia in modalità anonima, quindi connette il socket in tempo reale.

§ 04Come funziona

Quando si apre una sessione, il server genera un token effimero, specifico per conversazione. L'SDK lo usa per le chiamate REST e per il socket in tempo reale, lo rigenera in modo trasparente prima che scada e si riconnette con un backfill a prova di interruzioni quando la rete mobile cade.

Tutto è anonimo per impostazione predefinita: l'SDK genera un id visitatore durevole sul dispositivo, senza richiedere alcun login, e raccoglie facoltativamente un nome e un'email tramite il modulo pre-chat del tenant.

Sicurezza: non incorporare mai la chiave API del tuo tenant in un'app distribuita, perché è un segreto server-to-server. Il Flutter SDK usa esclusivamente il token di sessione per visitatore, che è sicuro per un client distribuito.

§ 05Cosa richiede lavoro lato server

L'esperienza completa di chat in primo piano funziona già oggi senza modifiche al backend. L'unica funzionalità che richiede lavoro sul server è il push in background, ovvero recapitare una notifica «un agente ha risposto» a un'app chiusa, perché attualmente il backend invia push solo agli agenti. Per abilitarlo sono necessari un registro dei push dei visitatori e il relativo fan-out; l'hook push dell'SDK rimane inattivo fino ad allora.

Attività di follow-up consigliate prima di un lancio pubblico: rate-limiting sulla creazione delle sessioni e sull'invio dei messaggi, un endpoint di refresh del token e il supporto al caricamento di HEIC/MOV per i contenuti multimediali dei telefoni.