帮你快速理解、总结文档立即下载

Android(View)

最近更新时间:2026-09-23 18:24:04
我的收藏
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 插件兼容性。
我们建议您根据上述指南,选择与项目要求完全匹配的版本组合。

集成并引入组件

说明:
Demo:CNB 完整 Demo(国内) 或者 GitHub 完整 Demo 开箱即用,5 分钟跑通聊天 + 音视频通话全功能。

下载源码

从 CNB 下载 TUIKit Android 源码或者 GitHub 下载 TUIKit Android 源码:
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 中引入对应模块(请按源码实际存放位置调整相对路径):
Kotlin DSL
Groovy DSL
// settings.gradle.kts

include(":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.gradle

include ':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 中添加依赖:
Kotlin DSL
Groovy DSL
// app/build.gradle.kts
dependencies {
implementation(project(":atomic_x"))
implementation(project(":uikit"))
implementation(project(":tuicallkit-kt"))
}
// app/build.gradle
dependencies {
implementation project(':atomic_x')
implementation project(':uikit')
implementation project(':tuicallkit-kt')
}

接入步骤

完成上述集成后,参考以下步骤,您仅需几行代码即可在项目中快速搭建会话列表、聊天、联系人等核心界面。

步骤1:配置用户鉴权

在 即时通信 IM 控制台 根据 UserID 获取 UserSig,用于后续登录时的用户鉴权。


步骤2:用户登录

登录鉴权后才能正常使用组件的功能。调用 LoginStore 的 login 接口,传入上文获取的 sdkAppID、userID、userSig 进行登录鉴权:
import io.trtc.tuikit.atomicxcore.api.CompletionHandler
import io.trtc.tuikit.atomicxcore.api.login.LoginStore
import com.tencent.cloud.tuikit.engine.call.TUICallEngine
import com.tencent.cloud.tuikit.engine.common.TUICommonDefine

LoginStore.shared.login(
context,
sdkAppID, // Int,控制台获取
userID, // String
userSig, // 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) {
// 登录失败,可弹框报错
}
}
)
注意:
在正式的生产环境中,建议在您的服务端生成 UserSig,在需要时由 App 向业务服务器发起请求获取动态 UserSig 进行鉴权。详见 服务端生成 UserSig。

步骤3:构建聊天界面

聊天界面使用 ChatPageView 展示和收发消息,通过 setup 传入 conversationID 即可。conversationID 的格式为:单聊 c2c_<对方 UserID>,群聊 group_<群 GroupID>。
import android.content.Context
import android.content.Intent
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import io.trtc.tuikit.chat.uikit.pages.ChatPageView

class ChatActivity : AppCompatActivity() {

override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)

// conversationID 格式:单聊 "c2c_<对方 UserID>",群聊 "group_<群 GroupID>"
val conversationID = intent.getStringExtra("conversationID") ?: return

val 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 组件中使用音视频通话功能。
说明:
如需使用音视频通话功能,请参考 开通音视频服务 文档开通服务。
如果没有开通音视频服务,点击 TUIKit 组件中的通话按钮会弹出报错提示。不会影响 TUIKit 其他功能正常使用。
import com.tencent.cloud.tuikit.engine.call.TUICallEngine
import com.tencent.cloud.tuikit.engine.common.TUICommonDefine

// 在步骤 2 的 LoginStore 登录成功回调中初始化 TUICallEngine
TUICallEngine.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 的应用 ID
String userID = "";
String userSig = "";

// 上述三个参数, 可以和您登录腾讯云 IM 的保持一致, 也可以使用不同的应用和用户

// 用户昵称。设置后,用户端转人工成功时,人工客服在工作台可见。您可将用户手机号,用户来源等信息写入昵称,长度限制500字节
// 注意!设置后,即时通信 IM 同 userID 的昵称也会被更新
// 如您不希望变更,请设置为 "" 或 null
String nickName = "";

// 用户头像。设置后,用户端转人工成功时,人工客服在工作台可见
// 注意!设置后,即时通信 IM 同 userID 的头像也会被更新
// 如您不希望变更,请设置为 "" 或 null
String avatar = "";

TencentAiDeskCustomer.getInstance().initWithProfile(context, SDKAppID, userID, userSig, nickName, avatar, new AIDeskCallback() {
@Override
public void onSuccess() {
startActivity(TencentAiDeskCustomer.getInstance().getCustomerServiceChatIntent(context));
}
@Override
public 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 企业版套餐 免费使用该表情包。




联系我们

如果您在接入或使用过程中有任何疑问或者建议,欢迎 联系我们 提交反馈。