实时客服，内置于
你的 Flutter 应用

§ 00概览

Flutter SDK 使用与你网站聊天相同的匿名挂件协议——因此客户可以从你的移动应用内部联系客服，进入的正是你的客服人员已经在共享收件箱中处理的那些会话。

它以两个软件包的形式发布：

• easylivechat — 无界面协议客户端及响应式状态，不含 UI
• easylivechat_ui — 预构建、可主题化的挂件——启动器、聊天界面、聊天前表单、附件、CSAT

§ 01安装

将该 SDK 添加到应用的 pubspec.yaml 中。大多数应用应选择 easylivechat_ui——它会重新导出核心包。只有在构建完全自定义的 UI 时，才单独使用无界面的 easylivechat。

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

需要 Flutter 3.19 或更高版本。socket_io_client 必须为 3.x 版本（Engine.IO v4），以便与服务端匹配。

§ 02快速开始（即插即用 UI）

使用你的工作区 slug 启动客户端一次，然后将启动器放入你的挂件树中。气泡会打开一个完全接通的聊天：聊天前表单、实时会话、输入状态、附件、CSAT、营业时间外的离线表单，外加服务端驱动的主题与 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() ]);

在你的仪表板中查找工作区 slug。启动器会在首次打开时延迟启动；传入一个持久化存储，以便访客身份在应用重启后依然保留。

§ 03无界面模式（构建你自己的 UI）

更喜欢使用自己的设计系统？直接驱动无界面客户端。一切都以 ValueListenables 和 Streams 的形式暴露出来，你可以将其绑定到任何状态管理方案。

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() 负责编排完整的生命周期：获取配置、恢复任何打开的会话、在聊天前表单处进行拦截或以匿名方式开始，然后连接实时 socket。

§ 04工作原理

当一个会话打开时，服务器会签发一个短期、按会话维度的令牌。SDK 将其用于 REST 调用和实时 socket，在过期前透明地重新签发，并在移动网络中断后通过无间隙的回填重新连接。

一切都以匿名优先：SDK 会在设备上生成一个持久的访客 id——无需登录——并可选地通过租户的聊天前表单收集姓名和电子邮箱。

安全提示：切勿将你的租户 API 密钥嵌入已发布的应用中——那是一个服务器到服务器的密钥。Flutter SDK 始终只使用按访客维度的会话令牌，该令牌对于分发型客户端是安全的。

§ 05哪些需要服务端工作

完整的前台聊天体验如今已无需任何后端改动即可使用。唯一需要服务端工作的能力是后台推送——向已关闭的应用投递“客服已回复”通知——因为后端目前仅向客服人员推送。要启用它，需要一个访客推送注册表和扇出机制；在此之前，SDK 的推送挂钩将保持静默。

在公开发布之前建议跟进的事项：对会话创建和消息发送进行限流、一个令牌刷新端点，以及针对手机媒体的 HEIC/MOV 上传支持。