跳到主要内容

快速上手

本教程是为了让新手快速了解融云即时通讯界面库（Flutter IMKit）。在本教程中，您可以体验集成 IMKit SDK 的基本流程和 IMKit 提供的 UI 界面。

前置条件​

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

  • 获取开发环境的应用 App Key。如不使用默认应用，您可创建应用，并获取对应环境 App Key 和 App Secret。

    提示

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

导入 SDK​

使用 Flutter IMKit 之前，您须导入 SDK。

初始化 SDK​

Dart
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
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. 监听 IM 连接状态的变化。建议在应用生命周期内设置。为了避免内存泄露，请在不需要监听时，将设置的监听器移除。
Dart
// 使用Provider监听连接状态
final engineProvider = Provider.of<RCKEngineProvider>(context, listen: false);

// 添加网络状态变化监听
engineProvider.networkChangeNotifier.addListener(() {
  final status = engineProvider.networkChangeNotifier.value;
  if (status != null) {
    // 处理连接状态变化
    print("连接状态变化: $status");
  }
});
  1. 在自定义登录页面，使用上一步获取的 token 连接融云，即模拟 userId 为 1 的用户连接到融云服务器。
Dart
final engineProvider = Provider.of<RCKEngineProvider>(context, listen: false);

// 初始化引擎
final engine = await engineProvider.engineCreate(
  appKey,  //应用后台获取
  options, //服务器地址
);

初始化配置参数（options）用于配置导航服务地址（naviServer）、文件服务地址（fileServer）、数据统计服务地址（statisticServer），以及是否开启推送（enablePush）。不传入任何配置时，将使用全部默认配置。SDK 默认连接北京数据中心。

配置详情请参考引擎配置。

Dart
// 连接服务器
await engineProvider.engineConnect(
  token,
  100,
  onResult: (code) {
    if (code == 0) {
        // 连接成功
        print("连接成功，用户ID: ${engineProvider.currentUserId}");
        // 可以在这里注册自定义消息类型
        engine.registerNativeCustomMessage(
          'CustomMessageType',
          RCIMIWNativeCustomMessagePersistentFlag.persisted
        );
        // 连接成功后跳转到主页面（请替换为您自己的路由名称）
        Navigator.pushNamed(context, '/your_main_page');
      } else {
        // 业务错误码，请根据相应的错误码作出对应处理
      }
  },
);

在 main.dart 注册 IMKit 路由​

初始化完成后，请在 main.dart 的 onGenerateRoute 中注册 IMKit 相关页面路由，确保 SDK 内部的图片预览、视频播放、文件预览与转发等页面可正常跳转：

Dart
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:rongcloud_im_kit/rongcloud_im_kit.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      onGenerateRoute: (settings) {
        switch (settings.name) {
          case '/chat':
            // Chat 页面参数解析
            final args = settings.arguments as Map<String, dynamic>?;
            final conversation = args?['conversation'] as RCIMIWConversation?;
            final rawBuilders = args?['customChatItemBubbleBuilders'];
            final Map<RCIMIWMessageType, CustomChatItemBubbleBuilder>?
                customChatItemBubbleBuilders;

            if (rawBuilders
                is Map<RCIMIWMessageType, CustomChatItemBubbleBuilder>) {
              customChatItemBubbleBuilders = rawBuilders;
            } else {
              customChatItemBubbleBuilders = null;
            }

            return MaterialPageRoute(
              builder: (context) => RCKChatPage(
                conversation: conversation,
                customChatItemBubbleBuilders: customChatItemBubbleBuilders,
              ),
              settings: settings,
            );
          case '/photo_preview':
            // 图片预览参数解析
            final args = settings.arguments as Map<String, dynamic>?;
            final currentIndex = args?['currentIndex'] as int? ?? 0;
            final images =
                args?['images'] as List<RCIMIWMediaMessage>? ?? [];

            return MaterialPageRoute(
              builder: (context) => RCKPhotoPreviewPage(
                currentIndex: currentIndex,
                images: images,
              ),
              settings: settings,
            );
          case '/video_player_page':
            // 视频播放页面参数解析
            final args = settings.arguments as Map<String, dynamic>?;
            final currentIndex = args?['currentIndex'] as int? ?? 0;
            final videos = args?['videos'] as List<RCIMIWMessage>? ?? [];

            return MaterialPageRoute(
              builder: (context) => RCKSightPlayerPage(
                currentIndex: currentIndex,
                videos: videos,
              ),
              settings: settings,
            );
          case '/file_preview':
            // 文件预览参数解析
            final args = settings.arguments as Map<String, dynamic>?;
            final fileMessage = args?['fileMessage'] as RCIMIWFileMessage?;
            final chatProvider = args?['chatProvider'] as RCKChatProvider?;

            if (fileMessage == null) {
              return MaterialPageRoute(
                builder: (context) => const Scaffold(
                  body: Center(child: Text('文件参数错误')),
                ),
              );
            }

            return MaterialPageRoute(
              builder: (context) => ChangeNotifierProvider.value(
                value: chatProvider,
                child: RCKFilePreviewPage(
                  fileMessage: fileMessage,
                ),
              ),
              settings: settings,
            );
          case '/forward':
            // 转发页面参数解析
            final args = settings.arguments as Map<String, dynamic>?;
            final chatProvider = args?['chatProvider'] as RCKChatProvider?;

            return MaterialPageRoute(
              builder: (context) => ChangeNotifierProvider.value(
                value: chatProvider,
                child: RCKForwardSelectPage(),
              ),
              settings: settings,
            );
        }

        return null;
      },
      // 其他 MaterialApp 配置...
      home: const SizedBox.shrink(),
    );
  }
}
提示

以上路由主要用于 IMKit SDK 内部调用。SDK 会在用户点击图片、视频、文件或转发按钮时自动使用这些路由跳转到对应页面。

如需跳转聊天、图片预览或文件预览，可以使用 Navigator.pushNamed 并传入对应参数。

收发消息​

对融云来说，只要提供对方的 userId，融云就可支持跟对方发起聊天。例如，A 需要发送消息给 B，只需要将 B 的 userId 告知融云服务即可发送消息。

提示
  • 融云服务器提供消息发送能力，消息发送过程中默认不会做任何权限校验。
  • 好友关系由开发者的应用服务器自行维护。

以下我们将利用 IMKit 默认提供的 UI 页面，进行简单的消息收发体验。

UI 界面​

IMKit SDK 已默认提供会话列表页面和聊天页面。客户端用户在会话列表页面可查看到当前所有的聊天会话，在聊天页面可进行消息查看、回复、发送等活动。

首次登录成功后，即跳转到默认会话列表界面，一般会显示一个空会话列表。客户端接收到消息后，会自动在会话列表页面展示新会话。

下图展示了 IMKit SDK 默认提供的会话列表页面。以下直接以默认会话列表为例。

使用会话列表页面

使用会话页面

测试收发消息​

在实际业务运行过程中，应用客户端可以通过用户 ID、群聊会话 ID、或聊天室 ID 等接收消息。

在本教程中，为了快速体验和测试 SDK，我们从控制台「北极星」开发者工具箱 [IM Server API 调试]页面向当前登录的用户发送一条文本消息，模拟单聊会话。

  1. 访问控制台「北极星」开发者工具箱的 [IM Server API 调试]页面。

  2. 在消息标签下，找到 消息服务 > 发送单聊消息 接口。

    以下模拟了从 UserId 为 2 的用户向 UserId 为 1 的用户发送一条文本消息。

  1. 客户端接收到消息后，自动在会话列表页面展示新的单聊会话。
  1. 点击会话，即可进入消息列表页面，发送消息。

后续步骤​

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

最后于 更新