即时通信 IM Android（View）

TUIKit 是基于 IM SDK 的一套 UI 组件库，可通过 UI 组件快速实现聊天、会话、搜索、关系链、群组等功能。本文介绍如何快速集成 TUIKit 并实现核心功能。
集成 TUIKit
TUIKit 采用数据驱动的响应式架构与原生 Android View 体系（非 Compose），以源码方式开放集成。它提供会话列表、聊天、联系人、搜索、群组等完整 UI 能力，并内置主题切换与全局配置。
环境要求
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 插件兼容性﻿。
我们建议您根据上述指南，选择与项目要求完全匹配的版本组合。
集成步骤
1. 从 GitHub 仓库 Tencent-RTC/TUIKit_Android 下载源码，将仓库根目录下的 chat、atomic_x（以及可选的、用于音视频通话的 call）文件夹整体复制到您的工程根目录下。复制完成后的目录结构如下：
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 中设置正确的相对路径即可。
2. 在 settings.gradle.kts 中引入对应模块（请按源码实际存放位置调整相对路径）：
Kotlin DSL
Groovy DSL
// settings.gradle.kts
﻿
// 引入 Chat UIKit 组件库（必要）
include(":uikit")
project(":uikit").projectDir = file("${settingsDir.path}/chat/uikit")
﻿
// 引入 AtomicX 基础 UI 组件库（必要）
include(":atomic_x")
project(":atomic_x").projectDir = file("${settingsDir.path}/atomic_x")
﻿
// 引入音视频通话组件（可选，集成音视频通话时需要）
include(":tuicallkit-kt")
project(":tuicallkit-kt").projectDir = file("${settingsDir.path}/call/tuicallkit-kt")
// settings.gradle
﻿
// 引入 Chat UIKit 组件库（必要）
include ':uikit'
project(':uikit').projectDir = new File(settingsDir, 'chat/uikit')
﻿
// 引入 AtomicX 基础 UI 组件库（必要）
include ':atomic_x'
project(':atomic_x').projectDir = new File(settingsDir, 'atomic_x')
﻿
// 引入音视频通话组件（可选，集成音视频通话时需要）
include ':tuicallkit-kt'
project(':tuicallkit-kt').projectDir = new File(settingsDir, 'call/tuicallkit-kt')
3. 在 app 模块的 build.gradle.kts 中添加依赖：
Kotlin DSL
Groovy DSL
// app/build.gradle.kts
dependencies {
    // TUIKit 组件库（必要）
    implementation(project(":uikit"))
    implementation(project(":atomic_x"))
    // 音视频通话（可选）
    implementation(project(":tuicallkit-kt"))
}
// app/build.gradle
dependencies {
    // TUIKit 组件库（必要）
    implementation project(':uikit')
    implementation project(':atomic_x')
    // 音视频通话（可选）
    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
﻿
LoginStore.shared.login(
    context,
    sdkAppID, // Int，控制台获取
    userID,   // String
    userSig,  // String，控制台或服务端生成
    object : CompletionHandler {
        override fun onSuccess() {
            // 登录成功，可跳转会话列表或聊天页
        }
        override fun onFailure(code: Int, desc: String) {
            // 登录失败，可弹框报错
        }
    }
)
注意：
在正式的生产环境中，建议在您的服务端生成 UserSig，在需要时由 App 向业务服务器发起请求获取动态 UserSig 进行鉴权。详见 服务端生成 UserSig。
步骤3：构建会话列表界面
会话列表只需创建 ConversationsPageView 并加入到您的布局即可。它会自动从本地读取最近会话，点击某个会话时通过 onConversationClick 回调返回该会话的 conversationID，您可据此跳转聊天界面。
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import io.trtc.tuikit.chat.uikit.pages.ConversationsPageView
﻿
class ConversationActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
﻿
        val conversationsPage = ConversationsPageView(this)
        conversationsPage.setHeaderTitle("消息")
﻿
        // 点击会话回调，conversationID 已带 c2c_ / group_ 前缀
        conversationsPage.onConversationClick = { conversationID ->
            // 跳转到您的聊天界面，并将 conversationID 传入（可参考步骤4 的 ChatActivity）
        }
        // 可选：搜索、发起单聊、创建群聊等入口回调
        conversationsPage.onSearchClick = { /* 跳转搜索页 */ }
        conversationsPage.onStartChatClick = { /* 发起单聊 */ }
        conversationsPage.onCreateGroupClick = { /* 创建群聊 */ }
﻿
        // 将会话列表设置为页面内容
        setContentView(conversationsPage)
    }
}
步骤4：构建聊天界面
聊天界面使用 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?) {
        // 必须设置 Material Components 主题，否则 ChatPageView 运行时会 Crash
        setTheme(com.google.android.material.R.style.Theme_MaterialComponents_Light_NoActionBar)
        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)
            })
        }
    }
}
注意：
承载聊天页的 Activity 必须设置 Material Components 主题（如 setTheme(com.google.android.material.R.style.Theme_MaterialComponents_Light_NoActionBar)），否则 ChatPageView 内部使用的 Material 控件会因缺少对应主题属性，在运行时直接 Crash。
说明：示例工程（demo）中提供了基于 ChatPageView 封装好的聊天页 ChatActivity（带标题栏、未读角标、群事件处理等），可直接复用或参考其实现进行自定义：ChatActivity.start(context, conversationID)。
步骤5：构建联系人界面
联系人界面使用 ContactsPageView 展示好友列表、群组列表等，通过 setup 设置点击回调。点击联系人或群组时跳转对应聊天界面。
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import io.trtc.tuikit.chat.uikit.pages.ContactsPageView
﻿
class ContactActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
﻿
        val contactsPage = ContactsPageView(this)
        contactsPage.setHeaderTitle("通讯录")
        contactsPage.setup(
            onContactClick = { contactInfo ->
                // 跳转到您的聊天界面，单聊会话 ID 为 "c2c_" + contactInfo.userID（可参考步骤4 的 ChatActivity）
            },
            onGroupClick = { contactInfo ->
                // 跳转到您的聊天界面，群聊会话 ID 为 "group_" + contactInfo.userID（可参考步骤4 的 ChatActivity）
            }
        )
        setContentView(contactsPage)
    }
}
步骤6：主题设置（可选）
TUIKit 通过 ThemeStore 支持设置主题色与浅色 / 深色主题切换。
import io.trtc.tuikit.atomicx.theme.Theme
import io.trtc.tuikit.atomicx.theme.ThemeStore
﻿
// 设置主题色
ThemeStore.shared(context).setPrimaryColor("#1C66E5")
﻿
// 切换浅色 / 深色主题
ThemeStore.shared(context).setTheme(Theme.lightTheme(context))
// ThemeStore.shared(context).setTheme(Theme.darkTheme(context))
步骤7：音视频通话（可选）
若需在聊天中支持音视频通话，请先 开通音视频服务，并在集成步骤中引入 :tuicallkit-kt 组件。登录成功后初始化 TUICallEngine，即可在 Chat 组件中正常使用该功能。
import com.tencent.cloud.tuikit.engine.call.TUICallEngine
import com.tencent.cloud.tuikit.engine.common.TUICommonDefine
﻿
TUICallEngine.createInstance(context).init(
    sdkAppID, userID, userSig,
    object : TUICommonDefine.Callback {
        override fun onSuccess() {
            // 初始化成功，可使用音视频通话能力
        }
﻿
        override fun onError(errCode: Int, errMsg: String) {
            // 初始化失败
        }
    }
)
常见问题
音视频常见问题
通话邀请的超时时间默认是多久？
通话邀请的默认超时时间是 30 秒。
在邀请超时时间内，被邀请者如果离线再上线，能否立即收到邀请？
如果是单聊通话邀请，被邀请者离线再上线可以收到通话邀请，TUIKit 内部会自动唤起通话邀请界面。
如果是群聊通话邀请，被邀请者离线再上线后会自动拉取最近 30 秒内的邀请，TUIKit 会自动唤起群通话界面。
其他常见问题
表情包的使用
为了尊重版权，IM Demo/TUIKit 工程中默认不包含大表情元素切图。正式上线商用前请您替换为自己设计或拥有版权的其他表情包。下图所示默认的小黄脸表情包版权归腾讯云所有，可有偿授权使用，如需获得授权，您可以通过升级至 IM 企业版套餐 免费使用该表情包。
﻿
﻿
﻿
联系我们
如果您在接入或使用过程中有任何疑问或者建议，欢迎 联系我们 提交反馈。
Android（View）

本页目录：

集成 TUIKit

环境要求

集成步骤

接入步骤

步骤1：配置用户鉴权

步骤2：用户登录

步骤3：构建会话列表界面

步骤4：构建聊天界面

步骤5：构建联系人界面

步骤6：主题设置（可选）

步骤7：音视频通话（可选）

常见问题

音视频常见问题

通话邀请的超时时间默认是多久？

在邀请超时时间内，被邀请者如果离线再上线，能否立即收到邀请？

其他常见问题

表情包的使用

联系我们
