tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
即时通信 IM
    文档
    Download PDF

    快速入门（Flutter）

    最后更新时间：2024-04-23 18:32:07
    下载PDF
      通过阅读本文，您可以了解集成 Flutter SDK 的方法。

      环境要求

      环境
      版本
      Flutter
      IM SDK 最低要求 Flutter 3.0.0 版本，TUIKit 集成组件库最低要求 Flutter 3.16.0 版本。
      Android
      Android Studio Dolphin | 2021.3.1 及以上版本，App 要求 Android 7.0 及以上版本设备。
      iOS
      Xcode 12.0 及以上版本，请确保您的项目已设置有效的开发者签名。

      支持平台

      我们致力于打造一套支持 Flutter 全平台的即时通信 IM SDK 及 TUIKit，帮助您一套代码，全平台运行。
      平台
      UIKit V2 ( tencent_cloud_chat)
      iOS
      支持
      支持
      支持
      Android
      支持
      支持
      支持
      支持，4.1.1+2版本起
      支持，0.1.5版本起
      即将支持...
      支持，4.1.9版本起
      支持，2.0.0版本起
      支持
      Windows
      支持，4.1.9版本起
      支持，2.0.0版本起
      支持
      混合开发 （将 Flutter SDK 添加至现有原生应用）
      5.0.0版本起支持
      1.0.0版本起支持
      支持
      说明
      Web 和 macOS 平台需要简单的几步额外引入，详情请查看本文 拓展更多平台。

      前序工作

      1. 您已 注册腾讯云，并完成 实名认证。
      2. 参照 创建并升级应用 创建应用，并记录好 SDKAppID。
      3. 在 IM 控制台 选择您的应用，在左侧导航栏依次点击 辅助工具->UserSig 生成&校验 ，创建两个 UserID 及其对应的 UserSig，复制UserID、签名（Key）、UserSig这三个，后续登录时会用到。
      说明
      该账户仅限开发测试使用。应用上线前，正确的 UserSig 签发方式是由服务器端生成，并提供面向 App 的接口，在需要 UserSig 时由 App 向业务服务器发起请求获取动态 UserSig。更多详情请参见 服务端生成 UserSig。

      选择合适的方案集成 Flutter SDK

      IM 提供了三种方式来集成，您可以选择最合适的方案来集成：
      集成方式
      适用场景
      IM Demo 是一个完整的聊天 App，代码已开源，如果您需要实现聊天类似场景，可以使用 Demo 进行二次开发。 可立即 体验 Demo。
      IM 的 UI 组件库UIKit提供了通用的 UI 组件，例如会话列表、聊天界面和联系人列表等，开发者可根据实际业务需求通过该组件库快速地搭建自定义 IM 应用。推荐优先使用该方案。
      如果 UIKit 不能满足您应用的界面需求，或者您需要比较多的定制，可以使用该方案。

      方案一：使用 Demo 修改

      本 Demo 程序，由新版 UIKit V2 构建。

      跑通 Demo

      1. 下载 Demo 源码、安装依赖：
      # Clone the code
      git clone https://github.com/TencentCloud/chat-demo-flutter.git
      
      # Checkout the 'v2' branch
      git checkout v2
      
      # Clean the project. Important
      flutter clean
      
      # Install dependencies
      flutter pub get
      2. 配置用户信息用于登录。
      打开 lib/config.dart, 并且配置 sdkappid, userid, and usersig 从此前步骤获取的。
      3. 运行应用.
      flutter run

      Demo 代码结构概览

      文件夹
      介绍
      lib
      程序核心目录
      lib/desktop
      桌面端适配相关代码
      lib/setting
      个人中心及设置页面相关代码
      lib 目录中的 lib/main.dart 文件，为本 Demo 程序运行的核心文件。可以看到，有下面几行关键代码。将 List<Widget> pages 的组件列表，传入 bottomNavigation 进行页面切换。
      pages = [
  const TencentCloudChatConversation(),
  const TencentCloudChatContact(),
  TencentCloudChatSettings(
    removeSettings: removeLocalSetting,
    setLoginState: changeLoginState,
  ),
];
      尽管新版 UIKit 有许多组件，但这些组件内置支持互相路由导航及引用关联。即，最简化使用，只需手动使用 TencentCloudChatConversation 会话列表组件和 TencentCloudChatContact 联系人组件，即可使用到全部 UIKit 关联组件，包括聊天组件，联系人及群组详情组件等。这些组件均可通过我们手动引入的组件，跳转过去。
      如果您对于 UIKit 的使用有较大自定义需求，可以查看 UIKit 的快速入门文档。

      方案二：含 UI 集成，使用 UIKit 组件库，快速集成聊天能力

      我们的全新 Flutter Chat UIKit V2 旨在为开发者提供一套全面的工具，以便轻松创建功能丰富的聊天应用程序。
      它采用模块化方法构建，让您可以选择所需的组件，同时保持应用程序轻量级和高效。
      UIKit 包括许多功能，如会话列表、消息处理、联系人列表、用户和群组资料、搜索功能等。
      
      
      
      此处仅简要说明引入使用 UIKit 的方式，详细快速入门文档请参阅此处。

      兼容性

      我们的 UIKit 支持手机端, 平板端和桌面端 UI 样式，并兼容 Android、iOS、macOS、Windows 和 Web（将在未来版本中支持）。
      它内置支持英语、简体中文、繁体中文、日语、韩语和阿拉伯语（支持阿拉伯RTL界面）以及亮色和暗色外观样式。

      要求

      Flutter版本：3.16或更高
      Dart版本：3.0或更高

      开始使用

      要开始使用我们的UIKit，首先导入基础包，tencent_cloud_chat。
      接下来，从以下列表中导入适合您需求的所需UI组件包：
      tencent_cloud_chat_message
      tencent_cloud_chat_conversation
      tencent_cloud_chat_contact
      tencent_cloud_chat_user_profile
      tencent_cloud_chat_group_profile
      tencent_cloud_chat_group_search (In Beta)
      下面展示了我们的UIKit的架构：
      
      
      

      集成

      有关 Chat UIKit 的集成，请参见 集成基本功能-Flutter。

      方案三：自实现 UI 集成

      前提条件

      您已经完成创建 Flutter 项目，或有可以基于的 Flutter 项目。

      接入步骤

      安装 IM SDK

      使用如下命令，安装 Flutter IM SDK 最新版本。
      flutter pub add tencent_cloud_chat_sdk
      说明： 如果您的项目还同时需要用于 Web 或 桌面端(macOS、Windows)，一些额外的步骤是需要的，具体情况各自的链接。

      完成 SDK 初始化

      调用initSDK，完成 SDK 初始化。
      将您的 sdkAppID 传入。
      import 'package:tencent_cloud_chat_sdk/enum/V2TimSDKListener.dart';
      import 'package:tencent_cloud_chat_sdk/enum/log_level_enum.dart';
      import 'package:tencent_cloud_chat_sdk/tencent_cloud_chat_sdk.dart';
      TencentImSDKPlugin.v2TIMManager.initSDK(
        sdkAppID: 0, // Replace 0 with the SDKAppID of your IM application when integrating
        loglevel: LogLevelEnum.V2TIM_LOG_DEBUG, // Log
        listener: V2TimSDKListener(),
      );
      在本步骤，您可以针对 IM SDK 挂载一些监听，主要包括网络状态及用户信息变更等，详情可参见 该文档。

      登录测试账户

      此时，您可以使用最开始的时候，在控制台生成的测试账户，完成登录验证。
      调用TencentImSDKPlugin.v2TIMManager.login方法，登录一个测试账户。
      当返回值res.code为0时，登录成功。
      import 'package:tencent_cloud_chat_sdk/tencent_cloud_chat_sdk.dart';
      V2TimCallback res = await TencentImSDKPlugin.v2TIMManager.login(
        userID: userID,
        userSig: userSig,
      );
      说明
      该账户仅限开发测试使用。应用上线前，正确的 UserSig 签发方式是将 UserSig 的计算代码集成到您的服务端，并提供面向 App 的接口，在需要 UserSig 时由您的 App 向业务服务器发起请求获取动态 UserSig。更多详情请参见 服务端生成 UserSig。

      发送消息

      此处以发送文本消息举例，其流程为：
      1. 调用 createTextMessage(String)创建一个文本消息。
      2. 根据其返回值，拿到消息 ID。
      3. 调用 sendMessage() 发送该ID的消息。receiver可填入您此前创建的另一个测试账户 ID。发送单聊消息无需填入groupID。
      代码示例：
      import 'package:tencent_cloud_chat_sdk/tencent_cloud_chat_sdk.dart';
      
      V2TimValueCallback<V2TimMsgCreateInfoResult> createMessage =
            await TencentImSDKPlugin.v2TIMManager
                .getMessageManager()
                .createTextMessage(text: "The text to create");
      
      String id = createMessage.data!.id!; // The message creation ID
      
      V2TimValueCallback<V2TimMessage> res = await TencentImSDKPlugin.v2TIMManager
            .getMessageManager()
            .sendMessage(
                id: id, // Pass in the message creation ID to
                receiver: "The userID of the destination user",
                groupID: "The groupID of the destination group",
                );
      说明
      如果发送失败，可能是由于您的 sdkAppID 不支持陌生人发送消息，您可至控制台开启，用于测试。
      请单击此链接，关闭好友关系链检查。

      获取会话列表

      在上一个步骤中，完成发送测试消息，现在可登录另一个测试账户，拉取会话列表。
      获取会话列表的方式有两种：
      1. 监听长连接回调，实时更新会话列表。
      2. 请求 API，根据分页一次性获取会话列表。
      常见应用场景为：
      在启动应用程序后立即获取会话列表，然后监听长连接以实时更新会话列表的变化。
      一次性请求会话列表
      为了获取会话列表，需要维护nextSeq，记录当前位置。
      import 'package:tencent_cloud_chat_sdk/tencent_cloud_chat_sdk.dart';
      
      String nextSeq = "0";
      
      getConversationList() async {
        V2TimValueCallback<V2TimConversationResult> res = await TencentImSDKPlugin
            .v2TIMManager
            .getConversationManager()
            .getConversationList(nextSeq: nextSeq, count: 10);
      
        nextSeq = res.data?.nextSeq ?? "0";
      }
      此时，您可以看到您在上一步中，使用另一个测试账号，发来消息的会话。
      监听长链接实时获取会话列表
      您在此步骤中，需要先在 SDK 上挂载监听，然后处理回调事件，更新 UI。
      1. 挂载监听。
      await TencentImSDKPlugin.v2TIMManager
       .getConversationManager()
       .setConversationListener(
         listener: new V2TimConversationListener(
           onConversationChanged: (List<V2TimConversation> list){
             _onConversationListChanged(list);
       },
           onNewConversation:(List<V2TimConversation> list){
             _onConversationListChanged(list);
       },
      2. 处理回调事件，将最新的会话列表展示在界面上。
      import 'package:tencent_cloud_chat_sdk/tencent_cloud_chat_sdk.dart';
      
      List<V2TimConversation> _conversationList = [];
      
      _onConversationListChanged(List<V2TimConversation> list) {
        for (int element = 0; element < list.length; element++) {
       int index = _conversationList.indexWhere(
         (item) => item!.conversationID == list[element].conversationID);
       if (index > -1) {
       _conversationList.setAll(index, [list[element]]);
       } else {
       _conversationList.add(list[element]);
       }
        }

      接收消息

      通过腾讯云 IM Flutter SDK 接收消息有两种方式：
      1. 监听长连接回调，实时获取消息变化，更新渲染历史消息列表。
      2. 请求 API，根据分页一次性获取历史消息。
      常见应用场景为：
      1. 界面进入新的会话后，首先一次性请求一定数量的历史消息，用于展示历史消息列表。
      2. 监听长链接，实时接收新的消息，将其添加进历史消息列表中。
      一次性请求历史消息列表
      每页拉取的消息数量不能太大，否则会影响拉取速度。建议此处设置为20左右。
      您应该动态记录当前页数，用于下一轮请求。
      示例代码如下：
      import 'package:tencent_cloud_chat_sdk/tencent_cloud_chat_sdk.dart';
      
        V2TimValueCallback<List<V2TimMessage>> res = await TencentImSDKPlugin
            .v2TIMManager
            .getMessageManager()
            .getGroupHistoryMessageList(
              groupID: "groupID",
              count: 20,
              lastMsgID: "",
            );
      
        List<V2TimMessage> msgList = res.data ?? [];
      
        // here you can use msgList to render your message list
          }
      监听长链接实时获取新消息
      历史消息列表初始化后，新消息来自长链接 V2TimAdvancedMsgListener.onRecvNewMessage。
      onRecvNewMessage回调被触发后，您可以按需将新消息添加进历史消息列表中。
      绑定监听器示例代码如下：
      import 'package:tencent_cloud_chat_sdk/tencent_cloud_chat_sdk.dart';
      
      final adVancesMsgListener = V2TimAdvancedMsgListener(
      onRecvNewMessage: (V2TimMessage newMsg) {
        _onReceiveNewMsg(newMsg);
      },
      /// ... other listeners related to message
      );
      
      TencentImSDKPlugin.v2TIMManager
          .getMessageManager()
          .addAdvancedMsgListener(listener: adVancesMsgListener);
      此时，您已基本完成 IM 模块开发，可以发送接收消息，也可以进入不同的会话。
      您可以继续完成 群组，用户资料，关系链，离线推送，本地搜索 等相关功能开发。

      拓展更多平台

      腾讯云IM for Flutter 相关SDK默认支持 Android, iOS 和 Windows 平台， 如果您需要拓展更多平台（Web 和 macOS），请参考本部分。

      Web

      我们的 SDK，TUIKit(tencent_cloud_chat_uikit) 0.1.5版本，无 UI SDK(tencent_cloud_chat_sdk) 4.1.1+2 版本起，可兼容 Web 端。
      相比 Android 和 iOS 端，需要一些额外步骤。如下：

      升级 Flutter 3.x 版本

      Flutter 3.x 版本 针对 Web 性能做了较多优化，强烈建议您使用其来开发 Flutter Web 项目。

      引入 JS

      说明
      如果您现有的 Flutter 项目不支持 Web，请在项目根目录下运行 flutter create . 添加 Web 支持。
      进入您项目的 web/ 目录，使用 npm 或 yarn 安装相关JS依赖。初始化项目时，根据屏幕指引，进行即可。
      cd web
      
      npm init
      
      npm i @tencentcloud/chat
      
      npm i tim-upload-plugin
      打开 web/index.html ，在 <head> </head> 间引入这JS文件。如下：
      <script src="./node_modules/tim-upload-plugin/index.js"></script>
      <script src="./node_modules/@tencentcloud/chat/index.js"></script>
<script src="./node_modules/@tencentcloud/chat/modules/group-module.js"></script>
<script src="./node_modules/@tencentcloud/chat/modules/relationship-module.js"></script>
<script src="./node_modules/@tencentcloud/chat/modules/signaling-module.js"></script>
      
      
      

      macOS

      macOS 平台需要其他配置。按照以下步骤配置 macOS 平台：
      1. 打开项目中的 macos/Runner/DebugProfile.entitlements和 macos/Runner/Release.entitlements 文件。
      2. 将以下行添加到每个文件:
      <key>com.apple.security.network.client</key>
      <true/>
      
      这些行授予您的应用程序作为客户端访问网络所需的权限。
      此配置对于确保您的应用程序与 macOS 平台上的后端服务之间的正确通信至关重要。

      常见问题

      iOS 端 Pods 依赖无法安装成功

      尝试方案一：配置运行后，如果报错，可以单击 Product > Clean Build Folder，清除产物后重新 pod install 或 flutter run

      尝试方案二：手动删除 ios/Pods 文件夹，及 ios/Podfile.lock 文件，并执行如下命令，重新安装依赖

      cd ios
      sudo gem install ffi
      pod install --repo-update

      Flutter 环境问题

      如您需得知 Flutter 的环境是否存在问题，请运行 Flutter doctor 检测 Flutter 环境是否装好。

      Windows 运行 Demo 报错怎么办？

      Nuget.exe not found, trying to download or use cached version.
      这个提示表明您的系统中没有找到 nuget.exe，因此程序尝试下载或使用缓存的版本。nuget.exe 是 NuGet 包管理器的命令行工具，用于在 .NET 项目中管理依赖项。
      要解决此问题，您可以手动下载并安装 nuget.exe。以下是操作步骤：
      1. 访问 NuGet 官方网站的下载页面：https://www.nuget.org/downloads
      2. 在 "Command-line" 部分，找到 "Windows x86 Commandline"，点击 "Download" 下载 nuget.exe。
      3. 将下载的 nuget.exe 文件保存到一个合适的位置，例如 C:\\NuGet。
      4. 将 nuget.exe 的路径添加到系统的环境变量 PATH 中。这样，您就可以在命令行中全局访问 nuget.exe 。

      错误码如何查询？

      SDK API 层面错误码，请查看 该文档。
      UIKit 相关错误及 UI 用户通知相关特有事件, 请查看 该文档.
      联系我们

      联系我们，为您的业务提供专属服务。

      联系我们
      技术支持

      如果你想寻求进一步的帮助，通过工单与我们进行联络。我们提供7x24的工单服务。

      提交工单
      7x24 电话支持
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      隐私条款服务条款缓存条款