快速上手
本教程是为了让新手快速了解融云即时通讯能力库(IMLib)。在本教程中,您可以体验集成 SDK 的基本流程和 IMLib 的基础通信能力。
前置条件
-
注册开发者账号。注册成功后,控制台会默认自动创建您的首个应用,默认生成开发环境下的 App Key,使用国内数据中心。
-
获取开发环境的应用 App Key。如不使用默认应用,请参考 如何创建应用,并获取对应环境 App Key 和 App Secret。
提示每个应用具有两个不同的 App Key,分别对应开发环境与生产环境,两个环境之间数据隔离。在您的应用正式上线前,可切换到使用生产环境的 App Key,以便上线前进行测试和最终发布。
-
阅读 SDK 变更说明。SDK 在 5.2.4、5.4.0 均有较大变更,请确保您已充分了解相关差异,例如接口回调的方式变更等。
环境要求
- Dart:2.15.0 ≧ dart < 3.0.0
- Flutter: ≧ 2.5.0
Demo 项目
融云 IMLib for Flutter SDK 提供了一个不含任何聊天界面的 Demo 项目,集中演示了各个接口的调用方法。
https://github.com/rongcloud/im-flutter-wrapper
导入 SDK
融云在 Flutter 平台以插件库形式提供 SDK,其中已包含 dart 层与 Android/iOS 平台层代码。
-
在项目的
pubspec.yaml
中添加依赖。SDK 最新版本可以查询 官方仓库。dependencies:
flutter:
sdk: flutter
rongcloud_im_wrapper_plugin: x.y.z -
在项目路径执行
flutter pub get
来下载相关插件。 -
导入头文件。
import 'package:rongcloud_im_wrapper_plugin/rongcloud_im_wrapper_plugin.dart';
关闭 Android 自动混淆
如果需要配置混淆,请参考 Android 文档。
如果不需要配置混淆,请关闭自动混淆。否则执行 flutter build apk
时,Flutter 会自动对 Android 代码进行混淆编译,导致 so 库找不到的错误。
android {
buildTypes {
release {
// Enables code shrinking, obfuscation, and optimization for only
// your project's release build type.
minifyEnabled false
// Enables resource shrinking, which is performed by the
// Android Gradle plugin.
shrinkResources false
}
}
...
}
初始化
在使用 SDK 所有功能之前,必须先调用此方法初始化 SDK。SDK 内的接口都需要通过 RCIMIWEngine
的对象进行调用,RCIMIWEngine
对象只能通过 create
进行获取,所以在调用 create
方法获取到实体对象后,开发者需要自行进行保存,以便后续接口调用。
初始化时需要传入上文获取的 App Key。
RCIMIWEngineOptions options = RCIMIWEngineOptions.create();
RCIMIWEngine engine = await RCIMIWEngine.create(appKey, options);
引擎配置请参见引擎配置。
获取用户 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 连接
-
使用
onConnectionStatusChanged
监听 IM 连接状态的变化,连接状态发生变化时返回 RCIMIWConnectionStatus。详见连接状态监听。engine?.onConnectionStatusChanged = (RCIMIWConnectionStatus? status) {
//...
}; -
使用上方获取的 Token,模拟 userId 为 1 的用户连接到融云服务器。调用结果会直接通过
connect
方法中传入的 RCIMIWConnectCallback 返回。RCIMIWConnectCallback? callback = RCIMIWConnectCallback(onDatabaseOpened: (int? code) {
//...
}, onConnected: (int? code, String? userId) {
//...
});
int? ret = await engine?.connect(token, timeout, callback:callback);
SDK 已实现自动重连机制,请参见连接。
监听消息
实现此功能需要开发者实现消息监听回调。
设置消息接收监听器,用于接收所有类型的实时或者离线消息。
message
接收到的消息对象left
当客户端连接成功后,服务端会将所有补偿消息以消息包的形式下发给客户端,最多每 200 条消息为一个消息包,即一个 Package, 客户端接受到消息包后,会逐条解析并通知应用。left 为当前消息包(Package)里还剩余的消息条数offline
消息是否离线消息hasPackage
是否在服务端还存在未下发的消息包
engine?.onMessageReceived = (RCIMIWMessage? message, int? left, bool? offline, bool? hasPackage) {
//...
};
发送消息
RCIMIWTextMessage? textMessage = await engine.createTextMessage(
conversationType,
targetId,
channelId,
text,
);
engine.sendMessage(message);
监听消息发送结果
engine?.onMessageAttached = (RCIMIWMessage? message) {
//...
};
engine?.onMessageSent = (int? code, RCIMIWMessage? message) {
//...
};
退出登录
int? ret = await engine?.disconnect(receivePush);
引擎销毁
await engine?.destroy();