TUIKit 是一套基于 IMSDK 的开源 UI 组件库。它采用数据驱动的响应式架构,以原生 Android View(而非 Jetpack Compose)构建,提供会话列表、聊天、联系人、搜索、群组等完整的 UI 组件能力,并内置主题切换与全局配置。本文介绍如何快速集成 TUIKit 并实现核心功能。
TUIKit 界面效果如下图所示:
会话列表页 | 聊天页 | 音视频通话 |
![]() | ![]() | ![]() |
方式1:AI 集成
在项目根目录执行
npx @tencent-rtc/trtc-agent-skills add --ide <您的 IDE>,将 trtc-agent-skills 安装到您本地 AI IDE 中(<您的 IDE> 可替换为 cursor、codebuddy、claude、codex,或使用 all 安装全部),辅助完成 TUIKit 集成。安装后,您可以直接向 AI 输入“集成 Android Chat”、“新增自定义消息类型”、“切换明暗主题”等需求,AI 将根据项目类型引导您完成代码接入、接口调用、UI 样式修改和测试数据生成等步骤。详情可参考 AI Coding Skills。方式2:手动集成
环境要求
Android Studio 2022.3.1 及之后的版本,JDK 17。
Android 6.0 及以上真机或模拟器。
工程需支持 Kotlin(TUIKit 使用 Kotlin 开发)。
minSdk >= 23 。
一个有效的腾讯云账号及 Chat 应用。可参考 开通服务 从控制台获取以下信息:
SDKAppID:App 在控制台获取的 Chat 应用的 ID,为应用的唯一标识。
SDKSecretKey:应用的密钥。
版本兼容性说明:
为确保构建环境稳定,请严格遵循官方兼容性要求进行配置:
Gradle、Android Gradle Plugin、JDK 与 Android Studio 的兼容性,请参阅 Android 官方文档:版本说明。
Kotlin、Android Gradle Plugin 与 Gradle 的版本对应关系,请参阅 Kotlin 官方文档:Kotlin-Gradle 插件兼容性。
我们建议您根据上述指南,选择与项目要求完全匹配的版本组合。
集成并引入组件
说明:
下载源码
git clone https://cnb.cool/tencent/cloud/trtc/TUIKit_Android// 或者 git clone https://github.com/Tencent-RTC/TUIKit_Android.git
将仓库根目录下的
chat、call 和 atomic_x 文件夹整体复制到您的工程根目录下。复制完成后的目录结构如下:YourApplication/├── app/ # 您的应用模块├── atomic_x/ # 基础 UI 组件库├── call/ # 音视频通话组件│ └── tuicallkit-kt/├── chat/ # Chat 源码│ ├── demo/ # 示例工程│ └── uikit/ # Chat UIKit 组件库├── settings.gradle.kts└── build.gradle.kts
说明:
TUIKit_Android 是包含多个产品的开源仓库,Chat 的 UI 源码位于
chat/ 目录下(chat/uikit 为 UIKit 组件库,chat/demo 为示例工程),其依赖的基础组件 atomic_x 与音视频通话组件 call/tuicallkit-kt 位于仓库根目录。模块目录可放在工程任意位置,只需在 settings.gradle.kts 中设置正确的相对路径即可。集成组件
1. 在
settings.gradle.kts 中引入对应模块(请按源码实际存放位置调整相对路径):// settings.gradle.ktsinclude(":atomic_x")project(":atomic_x").projectDir = file("${settingsDir.path}/atomic_x")include(":uikit")project(":uikit").projectDir = file("${settingsDir.path}/chat/uikit")include(":tuicallkit-kt")project(":tuicallkit-kt").projectDir = file("${settingsDir.path}/call/tuicallkit-kt")
// settings.gradleinclude ':atomic_x'project(':atomic_x').projectDir = new File(settingsDir, 'atomic_x')include ':uikit'project(':uikit').projectDir = new File(settingsDir, 'chat/uikit')include ':tuicallkit-kt'project(':tuicallkit-kt').projectDir = new File(settingsDir, 'call/tuicallkit-kt')
2. 在 app 模块的
build.gradle.kts 中添加依赖:// app/build.gradle.ktsdependencies {implementation(project(":atomic_x"))implementation(project(":uikit"))implementation(project(":tuicallkit-kt"))}
// app/build.gradledependencies {implementation project(':atomic_x')implementation project(':uikit')implementation project(':tuicallkit-kt')}
接入步骤
完成上述集成后,参考以下步骤,您仅需几行代码即可在项目中快速搭建会话列表、聊天、联系人等核心界面。
步骤1:配置用户鉴权

步骤2:用户登录
登录鉴权后才能正常使用组件的功能。调用
LoginStore 的 login 接口,传入上文获取的 sdkAppID、userID、userSig 进行登录鉴权:import io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.login.LoginStoreimport com.tencent.cloud.tuikit.engine.call.TUICallEngineimport com.tencent.cloud.tuikit.engine.common.TUICommonDefineLoginStore.shared.login(context,sdkAppID, // Int,控制台获取userID, // StringuserSig, // String,控制台或服务端生成object : CompletionHandler {override fun onSuccess() {// 登录成功TUICallEngine.createInstance(context).init(sdkAppID, userID, userSig,object : TUICommonDefine.Callback {override fun onSuccess() {// 初始化成功,可使用音视频通话能力}override fun onError(errCode: Int, errMsg: String) {// 初始化失败}})}override fun onFailure(code: Int, desc: String) {// 登录失败,可弹框报错}})
注意:
步骤3:构建聊天界面
聊天界面使用
ChatPageView 展示和收发消息,通过 setup 传入 conversationID 即可。conversationID 的格式为:单聊 c2c_<对方 UserID>,群聊 group_<群 GroupID>。import android.content.Contextimport android.content.Intentimport android.os.Bundleimport androidx.appcompat.app.AppCompatActivityimport io.trtc.tuikit.chat.uikit.pages.ChatPageViewclass ChatActivity : AppCompatActivity() {override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)// conversationID 格式:单聊 "c2c_<对方 UserID>",群聊 "group_<群 GroupID>"val conversationID = intent.getStringExtra("conversationID") ?: returnval chatPageView = ChatPageView(this)chatPageView.setup(conversationID = conversationID)setContentView(chatPageView)}companion object {fun start(context: Context, conversationID: String) {context.startActivity(Intent(context, ChatActivity::class.java).apply {putExtra("conversationID", conversationID)})}}}
说明:
示例工程(demo)中提供了基于
ChatPageView 封装好的聊天页 ChatActivity(带标题栏、未读角标、群事件处理等),可直接复用或参考其实现进行自定义:ChatActivity.start(context, conversationID)。步骤4:音视频通话
登录成功后初始化
TUICallEngine,即可在 TUIKit 组件中使用音视频通话功能。import com.tencent.cloud.tuikit.engine.call.TUICallEngineimport com.tencent.cloud.tuikit.engine.common.TUICommonDefine// 在步骤 2 的 LoginStore 登录成功回调中初始化 TUICallEngineTUICallEngine.createInstance(context).init(sdkAppID, userID, userSig,object : TUICommonDefine.Callback {override fun onSuccess() {// 初始化成功,可使用音视频通话能力}override fun onError(errCode: Int, errMsg: String) {// 初始化失败}})
步骤5:接入智能客服 Desk 用户端

若需同时集成智能客服 Desk 用户端,请先 开通智能客服 Desk 服务,并根据 Android 接入智能客服用户端 文档完成
com.tencentcloud.desk:aideskcustomer 包引入和配置,即可在您的应用中引入客服会话能力。int SDKAppID = 0; // 开通了智能客服 Desk 的应用 IDString userID = "";String userSig = "";// 上述三个参数, 可以和您登录腾讯云 IM 的保持一致, 也可以使用不同的应用和用户// 用户昵称。设置后,用户端转人工成功时,人工客服在工作台可见。您可将用户手机号,用户来源等信息写入昵称,长度限制500字节// 注意!设置后,即时通信 IM 同 userID 的昵称也会被更新// 如您不希望变更,请设置为 "" 或 nullString nickName = "";// 用户头像。设置后,用户端转人工成功时,人工客服在工作台可见// 注意!设置后,即时通信 IM 同 userID 的头像也会被更新// 如您不希望变更,请设置为 "" 或 nullString avatar = "";TencentAiDeskCustomer.getInstance().initWithProfile(context, SDKAppID, userID, userSig, nickName, avatar, new AIDeskCallback() {@Overridepublic void onSuccess() {startActivity(TencentAiDeskCustomer.getInstance().getCustomerServiceChatIntent(context));}@Overridepublic void onError(int code, String desc) {}});
AI 助手:知识咨询与代码集成
在接入 IM SDK 过程中,您可以通过 MCP 使用 AI 助手,快速完成知识咨询、报错排查和 UIKit 集成代码生成。支持 Web/Android/iOS/Flutter/uni-app 等平台,答案基于官方文档。适用于查询 SDK API、UI 组件用法、服务端 API 与 IM 产品配置等场景,立即体验,提出您的第一个问题。
常见问题
音视频常见问题
通话邀请的超时时间默认是多久?
通话邀请的默认超时时间是 30 秒。
在邀请超时时间内,被邀请者如果离线再上线,能否立即收到邀请?
如果是单聊通话邀请,被邀请者离线再上线可以收到通话邀请,TUIKit 内部会自动唤起通话邀请界面。
如果是群聊通话邀请,被邀请者离线再上线后会自动拉取最近 30 秒内的邀请,TUIKit 会自动唤起群通话界面。
如何移除音视频通话功能?
如果您不需要集成音视频通话功能,请在
settings.gradle.kts(或 settings.gradle) 和 app 模块的 build.gradle.kts(或 build.gradle) 文件中移除 tuicallkit-kt 依赖,并在步骤 3 创建聊天界面中关闭音视频通话开关,代码如下所示:val messageInputConfig = ChatMessageInputConfig(isShowAudioCall = false, // 关闭语音通话isShowVideoCall = false // 关闭视频通话)val chatPageView = ChatPageView(this)chatPageView.setup(conversationID = conversationID,messageInputConfig = messageInputConfig)
其他常见问题
表情包的使用
为了尊重版权,IM Demo/TUIKit 工程中默认不包含大表情元素切图。正式上线商用前请您替换为自己设计或拥有版权的其他表情包。下图所示默认的小黄脸表情包版权归腾讯云所有,可有偿授权使用,如需获得授权,您可以通过升级至 IM 企业版套餐 免费使用该表情包。




