快速上手
本教程是为了让新手快速了解融云即时通讯界面库(Flutter IMKit)。在本教程中,您可以体验集成 IMKit SDK 的基本流程和 IMKit 提供的 UI 界面。
前置条件
-
注册开发者账号。注册成功后,控制台会默认自动创建您的首个应用,默认生成开发环境下的 App Key,使用国内数据中心。
-
获取开发环境的应用 App Key。如不使用默认应用,请参考 如何创建应用,并获取对应环境 App Key 和 App Secret。
提示每个应用具有两个不同的 App Key,分别对应开发环境与生产环境,两个环境之间数据隔离。在您的应用正式上线前,可切换到使用生产环境的 App Key,以便上线前进行测试和最终发布。
导入 SDK
使用 Flutter IMKit 之前,您须导入 SDK。
初始化 SDK
import 'package:rongcloud_im_kit/rongcloud_im_kit.dart'; // 引入Provider配置
import 'package:provider/provider.dart';
// 确保应用已配置Provider
// 使用 RongCloudAppProviders.of 来包裹你的根组件
runApp(
RongCloudAppProviders.of(
MyApp(), // 你的根组件
additionalProviders: [ // 可以添加额外的Provider
// ...
],
),
);
// 获取Provider
final engineProvider = Provider.of<RCKEngineProvider>(context, listen: false);
// 初始化引擎
final engine = await engineProvider.engineCreate(
appKey,
options,
);
// 连接服务器
await engineProvider.engineConnect(
token,
100,
onResult: (code) {
if (code == 0) {
//连接成功
} else {
//错误提示
}
},
);
获取用户 Token
用户 Token 是与用户 ID 对应的身份验证令牌,是应用程序的用户在融云的唯一身份标识。应用客户端在使用融云即时通讯功能前必须与融云建立 IM 连接,连接时必须传入 Token。
在实际业务运行过程中,应用客户端需要通过应用的服务端调用 IM Server API 申请取得 Token。详见 Server API 文档 注册用户。
在本教程中,为了快速体验和测试 SDK,我们将使用控制台「北极星」开发者工具箱,从 API 调试页面调用 获取 Token 接口,获取到 userId 为 1 的用户的 Token。提交后,可在返回正文中取得 Token 字符串。
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"code":200,"userId":"1","token":"gxld6GHx3t1eDxof1qtxxYrQcjkbhl1V@sgyu.cn.example.com;sgyu.cn.example.com"}
- 监听 IM 连接状态的变化。建议在应用生命周期内设置。为了避免内存泄露,请在不需要监听时,将设置的监听器移除。
// 使用Provider监听连接状态
final engineProvider = Provider.of<RCKEngineProvider>(context, listen: false);
// 添加网络状态变化监听
engineProvider.networkChangeNotifier.addListener(() {
final status = engineProvider.networkChangeNotifier.value;
if (status != null) {
// 处理连接状态变化
print("连接状态变化: $status");
}
});
- 在自定义登录页面,使用上一步获取的 token 连接融云,即模拟 userId 为 1 的用户连接到融云服务器。
final engineProvider = Provider.of<RCKEngineProvider>(context, listen: false);
// 初始化引擎
final engine = await engineProvider.engineCreate(
appKey, //应用后台获取
options, //服务器地址
);
初始化配置(options
)中封装了导航服务地址(naviServer
)、文件服务地址(fileServer
)、数据统计服务地址(statisticServer
)配置,以及是否开启推送的开关(enablePush
)。不传入任何配置表示全部使用默认配置。SDK 默认连接北京数据中心。
配置详情详情可见引擎配置
// 连接服 务器
await engineProvider.engineConnect(
token,
100,
onResult: (code) {
if (code == 0) {
// 连接成功
print("连接成功,用户ID: ${engineProvider.currentUserId}");
// 可以在这里注册自定义消息类型
engine.registerNativeCustomMessage(
'CustomMessageType',
RCIMIWNativeCustomMessagePersistentFlag.persisted
);
// 连接成功后跳转到主页面
Navigator.pushNamed(context, '/main_page');
} else {
// 业务错误码,请根据相应的错误码作出对应处理
}
},
);
收发消息
对融云来说,只要提供对方的 userId,融云就可支持跟对方发起聊天。例如,A 需要发送消息给 B,只需要将 B 的 userId 告知融云服务即可发送消息。
- 融云服务器提供消息发送能力,消息发送过程中默认不会做任何权限校验。
- 好友关系由开发者的应用服务器自行维护。
以下我们将利用 IMKit 默认提供的 UI 页面,进行简单的消息收发体验。
UI 界面
IMKit SDK 已默认提供会话列表页面和聊天页面。客户端用户在会话列表页面可查看到当前所有的聊天会话,在聊天页面可进行消息查看、回复、发送等活动。
首次登录成功后,即跳转到默认会话列表界面,一般会显示一个空会话列表。客户端接收到消息后,会自动在会话列表页面展示新会话。
下图展示了 IMKit SDK 默认提供的会话列表页面。以下直接以默认会话列表为例。
测试收发消息
在实际业务运行过程中,应用客户端可以通过用户 ID、群聊会话 ID、或聊天室 ID 等接收消息。
在本教程中,为了快速体验和测试 SDK,我们从控制台「北极星」开发者工具箱 [IM Server API 调试]页面向当前登录的用户发送一条文本消息,模拟单聊会话。
-
访问控制台「北极星」开发者工具箱的 [IM Server API 调试]页面。
-
在消息标签下,找到 消息服务 > 发送单聊消息 接口。
以下模拟了从 UserId 为 2 的用户向 UserId 为 1 的用户发送一条文本消息。

- 客户端接收到消息后,自动在会话列表页面展示新的单聊会话。

- 点击会话,即可进入消息列表页面,发送消息。

后续步骤
以上步骤即 IMKit SDK 的快速集成与新手体验流程,您体验了基础 IM 通信能力和 UI 界面,更多详细介绍请参考后续各章节详细说明。