Flutter IMLib 快速开始
本页用 5 个步骤完成 Flutter 端 IMLib 接入：控制台取 AppKey / Token、导入 SDK、初始化、建立连接、收发消息与会话。示例方法名与参数来自冻结的 sdk-bindings.json。
- 控制台获取 AppKey 与 Token
在控制台创建应用并获取 AppKey；用户 Token 由业务服务先注册用户（
user.register）、再调用user.token.issue签发后下发到客户端（两步都需要服务端签名）。客户端只持有 Token，不得内置 AppSecret；Token 泄露时可调用服务端接口吊销。
- 导入 SDK
按「导入 SDK」安装依赖；包名：
impaas_imlib（IMLib）、impaas_imkit（IMKit）；IMKit 通过IMKit.start或 Widget 组合挂载。 - 初始化客户端
使用 AppKey（与服务端地址）初始化；初始化幂等：同 appkey 重复调用返回同一实例，不建立连接。
- 建立连接并订阅事件
使用 Token 调用 connect，成功后触发 CONNECTED；离线消息在 hello 后自动补发。
- 收发消息与会话
注册对端用户后发送第一条文本消息、监听 MESSAGES 事件并拉取会话列表。
1. 控制台获取 AppKey 与 Token
| 凭据 | 获取方式 | 使用位置 |
|---|---|---|
| AppKey | 控制台 → 应用 → 基本信息 | 初始化客户端（options.appkey） |
| 用户 Token | 业务服务注册用户（user.register）后调用 user.token.issue 签发（需签名） | connect(token) |
| AppSecret | 控制台 → 应用 → 密钥（仅服务端保存） | 服务端签发 Token / 调用 Open API |
AppSecret 只能保存在业务服务端；客户端产物中不得出现 AppSecret。示例中的 TOKEN 表示服务端签发的用户 Token。
本页及后续示例统一使用 https://im.example.com（服务端缺省端口）。
示例使用占位地址 https://im.example.com；本地联调请替换为你实际启动的服务端地址与端口（客户端与服务端必须指向同一地址）。
2. 导入 SDK
# impaas_imlib 尚未发布到 pub.dev：用 pubspec.yaml 的 path 依赖
# dependencies:
# impaas_imlib:
# path: /path/to/repo/sdk/flutter/imlib
# impaas_imkit: # 可选：IMKit
# path: /path/to/repo/sdk/flutter/imkit
flutter pub get # 首次/改 path 后执行；成功输出 Got dependencies!flutter pub add impaas_imlib 会因包不存在而失败（publish_to: none）。请使用上面的 pubspec path 依赖，然后执行 flutter pub get，成功输出为 Got dependencies!。
本仓库联调可直接指向 sdk/flutter/imlib；IMKit 同理指向 sdk/flutter/imkit。
3. 初始化
import 'package:impaas_imlib/impaas_imlib.dart';
// create 具备单次初始化语义：同 appKey 重复调用返回同一实例，不建立连接。
final engine = await RCIMIWEngine.create(
'YOUR_APP_KEY',
RCIMIWEngineOptions.create(naviServer: 'https://im.example.com'),
);4. 建立连接
// 连接状态与消息事件用引擎属性回调（5.x 基线风格）
engine.onConnectionStatusChanged = (status) => print('连接状态：${status}');
final code = await engine.connect(
TOKEN,
10, // 连接超时（秒）
callback: RCIMIWConnectCallback(
onConnected: (code, userId) => print('connected code=${code} userId=${userId}'),
onDatabaseOpened: (code) {},
),
);
if (code != 0) throw Exception('connect failed: ${code}');
// 退出登录：断开并销毁引擎（可再次 create）
await engine.disconnect(false);
await engine.destroy();5. 收发消息与会话
收发验证需要两个已注册用户：先注册对端（例如 user2）并签发它的 Token，再用对端账号建连接收。示例中的 user2 是“已存在的另一个用户”，不是任意字符串。
engine.onMessageReceived = (message, left, offline, hasPackage) {
// Message? message；offline=true 表示离线补发
};
final sent = await engine.sendTextMessage(1, 'user2', '你好，NI PaaS');
if (sent.code != 0) throw Exception(sent.msg);
final conversations = await engine.getConversationList();单聊发送给不存在的用户时，服务端返回 1004（用户不存在），当前连接可能因此被断开，随后发送调用返回 3001（连接已中断）。
这不是网络故障：注册对端用户（user.register）并重连后即可正常发送。排查时先确认两个 userId 都已注册且属于同一个 appkey。
如果脚本报 Unexpected token '<' 或看到 HTML，通常是服务端地址或端口不对（示例使用占位地址；本地联调要替换为实际端口）。
先用浏览器或 curl 访问服务端根路径确认可达，再检查 serverUrl 是否与启动参数一致。
同一进程内对同一个 appkey 初始化只会得到一个客户端实例（初始化幂等）：把两个账号塞进同一个实例会互相覆盖登录态，典型报错是 “cannot send to self”。
实测：同一进程内建两个客户端实例（不同 appkey 或先 destroy 再 create）可以互发；同 origin 的两个浏览器标签共享 deviceId，第二个客户端可能收不到投递。
因此本机验证“收发”请开两个进程，或开两个浏览器 profile（各自独立 localStorage/deviceId），每个进程/Profile 只登录一个用户。
下一步
- 初始化：全部初始化选项与平台差异
- 功能列表：103 个操作
- API 参考
- 状态码：处理 1002 / 3001 / 3002 等常见错误
- Flutter IMKit：需要现成 UI 时使用