通过阅读本文,您可以了解集成 Flutter SDK 的方法。
环境 | 版本 |
---|---|
Flutter | IM SDK 最低要求 Flutter 2.2.0版本,TUIKit 集成组件库最低要求 Flutter 2.10.0 版本。 |
Android | Android Studio 3.5及以上版本,App 要求 Android 4.1及以上版本设备。 |
iOS | Xcode 11.0及以上版本,请确保您的项目已设置有效的开发者签名。 |
我们致力于打造一套支持 Flutter 全平台的即时通信 IM SDK 及 TUIKit,帮助您一套代码,全平台运行。
平台 | 无 UI SDK (tencent_cloud_chat_sdk) | 含 UI 及基础业务逻辑 TUIKit (tencent_cloud_chat_uikit) |
---|---|---|
iOS | 支持 | 支持 |
Android | 支持 | 支持 |
Web | 支持,4.1.1+2版本起 | 支持,0.1.5版本起 |
macOS | 支持,4.1.9版本起 | 即将上线 |
Windows | 支持,4.1.9版本起 | 即将上线 |
混合开发 (将 Flutter SDK 添加至现有原生应用) | 5.0.0版本起支持 | 1.0.0版本起支持 |
说明:Web/macOS/Windows 平台需要简单的几步额外引入,详情请查看本文 拓展更多平台。
在开始接入前,您可以体验我们的 DEMO,快速了解腾讯云 IM Flutter 跨平台 SDK 及 TUIKit 的能力。
以下各版本 DEMO,均由同一 Flutter 项目引入TUIKit 制作打包而成。 Desktop(macOS/Windows)平台,SDK 已支持,DEMO 将于近期上线。
移动端 APP | WEB - H5 |
---|---|
iOS/Android APP,自动判断平台下载 ![]() |
手机扫码体验在线Web版DEMO ![]() |
SDKAppID
。UserID
、签名(Key)
、UserSig
这三个,后续登录时会用到。说明:该账户仅限开发测试使用。应用上线前,正确的
UserSig
签发方式是由服务器端生成,并提供面向 App 的接口,在需要UserSig
时由 App 向业务服务器发起请求获取动态UserSig
。更多详情请参见 服务端生成 UserSig。
IM 提供了三种方式来集成,您可以选择最合适的方案来集成:
集成方式 | 适用场景 |
---|---|
使用 DEMO 修改 | IM Demo 是一个完整的聊天 App,代码已开源,如果您需要实现聊天类似场景,可以使用 Demo 进行二次开发。 可立即 体验 Demo。 |
含 UI 集成 | IM 的 UI 组件库TUIKit 提供了通用的 UI 组件,例如会话列表、聊天界面和联系人列表等,开发者可根据实际业务需求通过该组件库快速地搭建自定义 IM 应用。推荐优先使用该方案。 |
自实现 UI 集成 | 如果 TUIKit 不能满足您应用的界面需求,或者您需要比较多的定制,可以使用该方案。 |
为帮助您更好的理解 IM SDK 的各 API,我们还提供了API Example,演示各 API 的调用及监听的触发。
下载 Demo 源码、安装依赖:
# Clone the code
git clone https://github.com/TencentCloud/tc-chat-demo-flutter.git
# Install dependencies
flutter pub get
运行 Demo 项目:
#启动demo项目,请替换SDK_APPID、KEY两个参数
flutter run --dart-define=SDK_APPID={YOUR_SDKAPPID} --dart-define=ISPRODUCT_ENV=false --dart-define=KEY={YOUR_KEY}
说明:
--dart-define=SDK_APPID={YOUR_SDKAPPID}
其中{YOUR_SDKAPPID}
需替换成您自己应用的 SDKAppID。--dart-define=ISPRODUCT_ENV=false
对开发生产环境做判断,如您是开发环境请用 false。--dart-define=KEY={YOUR_KEY}
其中{YOUR_KEY}
需替换成 第一部分:创建测试用户 中的密钥(Key)
信息。
im-flutter-uikit
目录。flutter pub get
main.dart
,配置 Edit Configurations
。Additional run args
,输入环境变量(SDKAPPID等信息)。如:# 请替换SDK_APPID、KEY两个参数
--dart-define=SDK_APPID={YOUR_SDKAPPID} --dart-define=ISPRODUCT_ENV=false --dart-define=KEY={YOUR_KEY}
说明:我们 Demo 的 UI 及业务逻辑部分,使用 Flutter TUIKit。Demo 层本身仅用于构建 App,处理导航跳转及调用实例化 TUIKit 中各个组件。
文件夹 | 介绍 |
---|---|
lib | 程序核心目录 |
lib/i18n | 国际化相关代码。这里的国际化,不包含 TUIKit 本身的国际化能力和国际化词条,您可按需引入 |
lib/src | 项目主体目录 |
lib/src/pages | 本 Demo 几个重点导航页。项目初始化完成后,由 app.dart 负责展示加载动画,并判断登录态,将用户引导至 login.dart 或 home_page.dart 。用户登录后,会将登录信息通过 shared_preference 插件,存储至本地。以后每次启动应用,若在本地发现原来的登录信息,则自动使用该信息进行登录,若无或登录失败,则引导至登录页。自动登录过程中,用户还在 app.dart ,可看到加载动画。home_page.dart 含一个底部 Tab,支撑本 Demo 的四个主功能页的切换。 |
lib/utils | 一些工具函数类 |
基本上,lib/src
内每个 dart 文件引入了一个 TUIKit 组件,在文件内,实例化组件后,即可渲染页面。
主要文件如下:
lib/src 主要文件 | 文件介绍 |
---|---|
add_friend.dart | 申请添加好友页面,使用 TIMUIKitAddFriend 组件 |
add_group.dart | 申请入群页面,使用 TIMUIKitAddGroup 组件 |
blacklist.dart | 黑名单列表页面,使用 TIMUIKitBlackList 组件 |
chat.dart | 主聊天页面,使用全套TUIKit聊天能力,使用 TIMUIKitChat 组件 |
chatv2.dart | 主聊天页面,使用原子化能力,使用 TIMUIKitChat 组件 |
contact.dart | 联系人页面 ,使用 TIMUIKitContact 组件 |
conversation.dart | 会话列表界面,使用 TIMUIKitConversation 组件 |
create_group.dart | 发起群聊页面,纯Demo实现,未使用组件 |
group_application_list.dart | 入群申请列表页面,使用 TIMUIKitGroupApplicationList 组件 |
group_list.dart | 群列表页面,使用 TIMUIKitGroup 组件 |
group_profile.dart | 群资料及群管理页面,使用 TIMUIKitGroupProfile 组件 |
newContact.dart | 联系人好友申请页面,使用 TIMUIKitNewContact 组件 |
routes.dart | Demo 的路由,导航至登录页 login.dart 或主页面 home_page.dart 。 |
search.dart | 全局搜索及会话内搜索页面,使用 TIMUIKitSearch (全局搜索) 及 TIMUIKitSearchMsgDetail (会话内搜索) 组件 |
user_profile.dart | 用户信息及关系链维护页面,使用 TIMUIKitProfile 组件 |
大部分 TUIKit 组件需要传入导航跳转方法,因此需要 Demo 层处理 Navigator
。
以上介绍了我们的 Demo,您可以直接直接修改它二次开发,或参照它实现您的业务需求。
TUIKit 是基于腾讯云 IM SDK 的一款 UI 组件库,它提供了一些通用的 UI 组件,例如会话列表、聊天界面和联系人列表等,开发者可根据实际业务需求通过该组件库快速地搭建自定义 IM 应用。参见 TUIKit 图文介绍。
本部分为快速使用 TUIKit 介绍,详细入门指引可参见 TUIKit 集成基础功能。
您已经完成创建 Flutter 项目,或有可以基于的 Flutter 项目。
由于 TUIKit 运行,需要拍摄/相册/录音/网络等权限,需要您在 Native 的文件中手动声明,才可正常使用相关能力。
Android
打开 android/app/src/main/AndroidManifest.xml
,在 <manifest></manifest>
中,添加如下权限。
<uses-permission
android:name="android.permission.INTERNET"/>
<uses-permission
android:name="android.permission.RECORD_AUDIO"/>
<uses-permission
android:name="android.permission.FOREGROUND_SERVICE"/>
<uses-permission
android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission
android:name="android.permission.VIBRATE"/>
<uses-permission
android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>
<uses-permission
android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission
android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission
android:name="android.permission.CAMERA"/>
iOS
打开 ios/Podfile
,在文件末尾新增如下权限代码。
post_install do |installer|
installer.pods_project.targets.each do |target|
flutter_additional_ios_build_settings(target)
target.build_configurations.each do |config|
config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
'$(inherited)',
'PERMISSION_MICROPHONE=1',
'PERMISSION_CAMERA=1',
'PERMISSION_PHOTOS=1',
]
end
end
end
说明:如您需要用到推送能力,还需要添加推送相关权限,详情可查看 Flutter 厂商消息推送插件集成指南。
我们的 TUIkit 已经内含 IM SDK,因此仅需安装tencent_cloud_chat_uikit
,不需要再安装基础 IM SDK。
#在命令行执行:
flutter pub add tencent_cloud_chat_uikit
如果您的项目需要支持 Web,请在执行后续步骤前,查看 Web 兼容说明章节,引入 JS 文件。
TIMUIKitCore.getInstance()
,再调用初始化函数 init()
,并将您的sdkAppID
传入。/// main.dart
import 'package:tencent_cloud_chat_uikit/tencent_cloud_chat_uikit.dart';
final CoreServicesImpl _coreInstance = TIMUIKitCore.getInstance();
@override
void initState() {
_coreInstance.init(
sdkAppID: 0, // Replace 0 with the SDKAppID of your IM application when integrating
// language: LanguageEnum.en, // 界面语言配置,若不配置,则跟随系统语言
loglevel: LogLevelEnum.V2TIM_LOG_DEBUG,
onTUIKitCallbackListener: (TIMCallback callbackValue){}, // [建议配置,详见此部分](https://www.tencentcloud.com/document/product/1047/50054#onTUIKitCallbackListener)
listener: V2TimSDKListener());
super.initState();
}
}
说明:请在本步骤 await 初始化完成后,才可执行后续步骤。
_coreInstance.login
方法,登录一个测试账户。import 'package:tencent_cloud_chat_uikit/tencent_cloud_chat_uikit.dart';
final CoreServicesImpl _coreInstance = TIMUIKitCore.getInstance();
_coreInstance.login(userID: userID, userSig: userSig);
说明:该账户仅限开发测试使用。应用上线前,正确的
UserSig
签发方式是由服务器端生成,并提供面向 App 的接口,在需要UserSig
时由 App 向业务服务器发起请求获取动态UserSig
。更多详情请参见 服务端生成 UserSig。
您可以以会话列表作为您的 IM 功能首页,其涵盖了与所有有聊天记录的用户及群聊的会话。
请创建一个 Conversation
类,body
中使用 TIMUIKitConversation
组件,渲染会话列表。
您仅需传入一个 onTapItem
事件的处理函数,用于跳转至具体会话聊天页的导航。关于 Chat
类,会在下一步讲解。
import 'package:flutter/material.dart';
import 'package:tencent_cloud_chat_uikit/tencent_cloud_chat_uikit.dart';
class Conversation extends StatelessWidget {
const Conversation({Key? key}) : super(key: key);
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: const Text(
"Message",
style: TextStyle(color: Colors.black),
),
),
body: TIMUIKitConversation(
onTapItem: (selectedConv) {
Navigator.push(
context,
MaterialPageRoute(
builder: (context) => Chat(
selectedConversation: selectedConv,
),
));
},
),
);
}
}
该页面由顶部主体聊天历史记录及底部发送消息模块组成。
请创建一个 Chat
类,body
中使用 TIMUIKitChat
组件,渲染聊天页面。
您最好传入一个 onTapAvatar
事件的处理函数,用于跳转至联系人的详细信息页。关于 UserProfile
类,会在下一步讲解。
import 'package:flutter/material.dart';
import 'package:tencent_cloud_chat_uikit/tencent_cloud_chat_uikit.dart';
class Chat extends StatelessWidget {
final V2TimConversation selectedConversation;
const Chat({Key? key, required this.selectedConversation}) : super(key: key);
String? _getConvID() {
return selectedConversation.type == 1
? selectedConversation.userID
: selectedConversation.groupID;
}
@override
Widget build(BuildContext context) {
return TIMUIKitChat(
conversationID: _getConvID() ?? '', // groupID or UserID
conversationType: selectedConversation.type ?? 1, // Conversation type
conversationShowName: selectedConversation.showName ?? "", // Conversation display name
onTapAvatar: (_) {
Navigator.push(
context,
MaterialPageRoute(
builder: (context) => UserProfile(userID: userID),
));
}, // Callback for the clicking of the message sender profile photo. This callback can be used with `TIMUIKitProfile`.
);
}
该页面默认,可在只传入一个 userID
的情况下,自动根据是否是好友,生成用户详情页。
请创建一个 UserProfile
类,body
中使用 TIMUIKitProfile
组件,渲染用户详情及关系链页面。
说明:如果您希望自定义该页面,请优先考虑使用
profileWidgetBuilder
传入需自定义的profile组件并配合profileWidgetsOrder
确定纵向排列顺序;如果无法满足,才可使用builder
。
import 'package:flutter/material.dart';
import 'package:tencent_cloud_chat_uikit/tencent_cloud_chat_uikit.dart';
class UserProfile extends StatelessWidget {
final String userID;
const UserProfile({required this.userID, Key? key}) : super(key: key);
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: const Text(
"Message",
style: TextStyle(color: Colors.black),
),
),
body: TIMUIKitProfile(
userID: widget.userID,
),
);
}
}
此时,您的应用已经可以完成消息收发,管理好友关系,展示用户详情及展示会话列表。
您还可以继续使用以下 TUIKit 插件快速实现完整 IM 功能。
TIMUIKitProfile
基本一致。TIMUIKitUnreadCount
小红点组件,其会自动挂载监听。TIMUIKitSearch
全局搜索组件,支持全局搜索联系人/群组/聊天记录,也支持使用 TIMUIKitSearchMsgDetail
在特定会话中搜索聊天记录。两种模式取决于是否传入 conversation
。您已经完成创建 Flutter 项目,或有可以基于的 Flutter 项目。
使用如下命令,安装 Flutter IM SDK 最新版本。
在命令行执行:
flutter pub add tencent_cloud_chat_sdk
说明:
如果您的项目还同时需要用于 Web 或 桌面端(macOS、Windows),一些额外的步骤是需要的,具体情况各自的链接。
调用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。
此处以发送文本消息举例,其流程为:
createTextMessage(String)
创建一个文本消息。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 不支持陌生人发送消息,您可至控制台开启,用于测试。
请单击此链接,关闭好友关系链检查。
在上一个步骤中,完成发送测试消息,现在可登录另一个测试账户,拉取会话列表。
获取会话列表的方式有两种:
常见应用场景为:
在启动应用程序后立即获取会话列表,然后监听长连接以实时更新会话列表的变化。
为了获取会话列表,需要维护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。
挂载监听。
await TencentImSDKPlugin.v2TIMManager
.getConversationManager()
.setConversationListener(
listener: new V2TimConversationListener(
onConversationChanged: (List<V2TimConversation> list){
_onConversationListChanged(list);
},
onNewConversation:(List<V2TimConversation> list){
_onConversationListChanged(list);
},
处理回调事件,将最新的会话列表展示在界面上。
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 Ffltter SDK 接收消息有两种方式:
常见应用场景为:
每页拉取的消息数量不能太大,否则会影响拉取速度。建议此处设置为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 模块开发,可以发送接收消息,也可以进入不同的会话。
您可以继续完成 群组,用户资料,关系链,离线推送,本地搜索 等相关功能开发。
详情可查看 自实现 UI 集成 SDK 文档。
除 SDK 及 TUIKit 本体基础功能外,我们还提供了四个选装插件,帮助您丰富 IM 能力。
说明:如果您有好的想法及建议,欢迎随时 联系我们。
腾讯云IM for Flutter 相关SDK默认支持 Android / iOS平台, 如果您需要拓展更多平台( Web/Desktop ),请参考本部分。
我们的 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 版本 针对 Web 性能做了较多优化,强烈建议您使用其来开发 Flutter Web 项目。
flutter pub add tencent_im_sdk_plugin_web
说明:如果您现有的 Flutter 项目不支持 Web,请在项目根目录下运行
flutter create .
添加 Web 支持。
进入您项目的 web/
目录,使用 npm
或 yarn
安装相关JS依赖。初始化项目时,根据屏幕指引,进行即可。
cd web
npm init
npm i tim-js-sdk
npm i tim-upload-plugin
打开 web/index.html
,在
间引入这JS文件。如下:
<script src="./node_modules/tim-upload-plugin/index.js"></script>
<script src="./node_modules/tim-js-sdk/tim-js-friendship.js"></script>
我们的无 UI SDK(tencent_cloud_chat_sdk) 4.1.9 版本起,可完美兼容 macOS、Windows 端。相比 Android 和 iOS 端,需要一些额外步骤。如下:
从 Flutter 3.0 版本起,才可用于打包 desktop 端,因此,如需使用,请升级至 Flutter 3.x 版本。
flutter pub add tencent_im_sdk_plugin_desktop
打开 macos/Runner/DebugProfile.entitlements
文件。
在 <dict></dict>
中,加入如下 key-value
键值对。
<key>com.apple.security.app-sandbox</key>
<false/>
pod install
或 flutter run
ios/Pods
文件夹,及 ios/Podfile.lock
文件,并执行如下命令,重新安装依赖搭载新款 Apple Silicon 的 Mac 设备,如 M1。
cd ios
sudo arch -x86_64 gem install ffi
arch -x86_64 pod install --repo-update
搭载老款 Intel 芯片的 Mac 设备。
cd ios
sudo gem install ffi
pod install --repo-update
请将您的 Apple Watch 调整至飞行模式,并将 iPhone 的蓝牙功能通过 设置 => 蓝牙
彻底关闭。
重新启动 Xcode(若打开),并重新 flutter run
即可。
如您需得知 Flutter 的环境是否存在问题,请运行 Flutter doctor 检测 Flutter 环境是否装好。
打开 android\app\src\main\AndroidManifest.xml
,根据如下,补全 xmlns:tools="http://schemas.android.com/tools"
/ android:label="@string/android_label"
及 tools:replace="android:label"
。
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="替换成您的 Android 端包名"
xmlns:tools="http://schemas.android.com/tools">
<application
android:label="@string/android_label"
tools:replace="android:label"
android:icon="@mipmap/ic_launcher" // 指定一个 icon 路径
android:usesCleartextTraffic="true"
android:requestLegacyExternalStorage="true">
打开 android\app\build.gradle
,补全 defaultConfig
中 minSdkVersion
及 targetSdkVersion
。
defaultConfig {
applicationId "" // 替换成您的Android端包名
minSdkVersion 21
targetSdkVersion 30
}
本页内容是否解决了您的问题?