SDK Flutter — EasyLiveChat Docs

§ 00Visão geral

O SDK Flutter fala o mesmo protocolo anônimo de widget que o chat do seu site usa — assim, os clientes podem entrar em contato com o suporte de dentro do seu app móvel, nas mesmas conversas que seus agentes já atendem na caixa de entrada compartilhada.

Ele é distribuído como dois pacotes:

easylivechat — cliente headless do protocolo mais estado reativo, sem interface
easylivechat_ui — widgets pré-construídos e personalizáveis — launcher, tela de chat, formulário de pré-chat, anexos, CSAT

§ 01Instalação

Adicione o SDK ao pubspec.yaml do seu app. A maioria dos apps vai querer o easylivechat_ui — ele reexporta o core. Recorra ao easylivechat headless sozinho apenas quando estiver criando uma interface totalmente personalizada.

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

Requer o Flutter 3.19 ou mais recente. O socket_io_client precisa ser uma versão 3.x (Engine.IO v4) para corresponder ao servidor.

§ 02Início rápido (interface pronta para usar)

Inicialize o cliente uma vez com o slug do seu workspace e, em seguida, insira um launcher na sua árvore de widgets. A bolha abre um chat totalmente integrado: formulário de pré-chat, thread em tempo real, indicação de digitação, anexos, CSAT, um formulário offline para fora do horário de atendimento, além de temas e RTL definidos pelo servidor.

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() ]);

Encontre o slug do seu workspace no seu painel. O launcher é inicializado de forma lazy na primeira abertura; passe um armazenamento durável para que a identidade do visitante sobreviva às reinicializações do app.

§ 03Headless (crie a sua própria interface)

Prefere o seu próprio design system? Conduza o cliente headless diretamente. Tudo é exposto como ValueListenables e Streams que você pode vincular a qualquer gerenciamento de estado.

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() orquestra todo o ciclo de vida: busca a configuração, retoma qualquer conversa em aberto, faz a triagem pelo formulário de pré-chat ou inicia anonimamente e, então, conecta o socket em tempo real.

§ 04Como funciona

Quando uma sessão é aberta, o servidor gera um token de curta duração, por conversa. O SDK o utiliza para as chamadas REST e para o socket em tempo real, gera-o novamente de forma transparente antes que ele expire e reconecta com um backfill à prova de lacunas quando a rede móvel cai.

Tudo é anônimo por padrão: o SDK gera um id de visitante durável no dispositivo — sem necessidade de login — e, opcionalmente, coleta um nome e um e-mail por meio do formulário de pré-chat do tenant.

Segurança: nunca incorpore a chave de API do seu tenant em um app distribuído — esse é um segredo de servidor para servidor. O SDK Flutter usa apenas o token de sessão por visitante, que é seguro para um cliente distribuído.

§ 05O que precisa de trabalho no lado do servidor

A experiência completa de chat em primeiro plano já funciona hoje, sem alterações no backend. O único recurso que exige trabalho no servidor é o push em segundo plano — entregar uma notificação de “o agente respondeu” a um app fechado — porque o backend atualmente envia push apenas para os agentes. É necessário um registro de push de visitantes e um fan-out para habilitá-lo; o hook de push do SDK permanece inerte até lá.

Acompanhamentos recomendados antes de um lançamento público: limitação de taxa na criação de sessões e no envio de mensagens, um endpoint de atualização de token e suporte a upload em HEIC/MOV para mídias de celular.

Sugerir uma edição