跳到主要内容

快速上手

本教程旨在帮助开发者快速了解和掌握 IMLib SDK(融云即时通讯能力库)的基础集成流程与核心通信能力。通过本教程,您将完成从 IMLib SDK 导入、初始化、设置监听、建立连接和收发消息等全流程操作。

前置条件

  • 注册开发者账号。注册成功后,控制台会默认自动创建您的首个应用,默认生成开发环境下的 App Key,使用国内数据中心。

  • 获取开发环境的应用 App Key。如不使用默认应用,请参考 如何创建应用,并获取对应环境 App Key 和 App Secret

    提示

    每个应用具有两个不同的 App Key,分别对应开发环境与生产环境,两个环境之间数据隔离。在您的应用正式上线前,可切换到使用生产环境的 App Key,以便上线前进行测试和最终发布。

  • 阅读 SDK 变更说明。SDK 在 5.2.4、5.4.0 均有较大变更,请确保您已充分了解相关差异,例如接口回调的方式变更等。

环境要求

版本大于等于 5.12.1

  • Dart:≥2.15.0 < 4.0.0
  • Flutter: ≧ 2.5.0

版本小于 5.12.1

  • Dart:≥ 2.15.0 < 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 平台层代码。

  1. 在项目的 pubspec.yaml 中添加依赖。SDK 最新版本可以查询 官方仓库

    yaml
    dependencies:
    flutter:
    sdk: flutter

    rongcloud_im_wrapper_plugin: x.y.z
  2. 在项目路径执行 flutter pub get 来下载相关插件。

  3. 导入头文件。

    Dart
    import 'package:rongcloud_im_wrapper_plugin/rongcloud_im_wrapper_plugin.dart';

关闭 Android 自动混淆

如果需要配置混淆,请参考 Android 文档

如果不需要配置混淆,请关闭自动混淆。否则执行 flutter build apk 时,Flutter 会自动对 Android 代码进行混淆编译,导致 so 库找不到的错误。

Groovy
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
}
}
...
}

初始化 IMLib SDK

为确保您可以正常连接融云服务器和使用融云即时通讯服务(IM 服务),您须调用 create 方法初始化 IMLib SDK。初始化前,您须在融云控制台中获取 App Key,并设置好 RCIMIWEngineOptions(初始化配置)。详见初始化。 RCIMIWEngineOptions 中封装了 RCIMIWAreaCode (数据中心的区域码),naviServer(导航服务地址)、fileServer(文件服务地址)、statisticServer(数据统计服务地址),enablePush(推送的开关)。详见引擎配置。(注意: RCIMIWAreaCode 跟 naviServer 只设置其中一个即可)。 如果您使用北京数据中心,则不需设置 RCIMIWAreaCode 或者 naviServer ,IMLib SDK 默认连接北京数据中心。

Dart
RCIMIWEngineOptions options = RCIMIWEngineOptions.create();
RCIMIWEngine engine = await RCIMIWEngine.create(appKey, options);

监听消息

实现此功能需要开发者实现消息监听回调。

设置消息接收监听器,用于接收所有类型的实时或者离线消息。

  1. message 接收到的消息对象
  2. left 当客户端连接成功后,服务端会将所有补偿消息以消息包的形式下发给客户端,最多每 200 条消息为一个消息包,即一个 Package, 客户端接受到消息包后,会逐条解析并通知应用。left 为当前消息包(Package)里还剩余的消息条数
  3. offline 消息是否离线消息
  4. hasPackage 是否在服务端还存在未下发的消息包
Dart
engine?.onMessageReceived = (RCIMIWMessage? message, int? left, bool? offline, bool? hasPackage) {
//...
};

连接融云 IM 服务器

  1. 为模拟用户通过融云 IM 服务器收发消息,您需要首先注册一个用户。在实际业务中,应用客户端通过应用服务端调用融云 IM Server API 获取 token。详见 Server API 文档注册用户。在本教程中,为了快速体验融云服务,您可在控制台「北极星」的 API 调试页面调用获取 Token 接口,获取到 userId 为 1 的用户的 Token。调用返回如下:
HTTP
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"}
  1. 设置连接监听器来实时获取连接状态。您可以将连接状态通过 UI 反馈给用户(例如提示 “网络连接中断” 或 “已重新连接”),提高用户体验。建议在应用生命周期内设置 IM 连接状态监听器,并在不需要的时候移除监听器。详见连接状态监听
Dart
 engine?.onConnectionStatusChanged = (RCIMIWConnectionStatus? status) {
//...
};
  1. 调用 connect 方法,将 userId 为 1 的用户连接融云 IM 服务。注:IMLib SDK 有重连机制,因此一个应用生命周期内调用一次 connect 即可,详见连接
Dart
RCIMIWConnectCallback? callback = RCIMIWConnectCallback(onDatabaseOpened: (int? code) {
//...
}, onConnected: (int? code, String? userId) {
//...
});

int? ret = await engine?.connect(token, timeout, callback:callback);

连接成功的回调,onConnected 参数说明:

  • code 连接状态码,0 代表连接成功。
  • userId 连接成功的用户 ID。

发送消息

Dart
RCIMIWTextMessage? textMessage = await engine.createTextMessage(
conversationType,
targetId,
channelId,
text,
);
RCIMIWSendMessageCallback? callback = RCIMIWSendMessageCallback(

onMessageSaved: (RCIMIWMessage? message) {
//...
},
onMessageSent: (int? code, RCIMIWMessage? message){
//...
});

int? ret = await engine?.sendMessage(textMessage, callback:callback);

退出登录

Dart
int? ret = await engine?.disconnect(receivePush);

引擎销毁

Dart
await engine?.destroy();