Android(View)

最近更新时间:2026-06-17 14:33:03

我的收藏
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 下载源码,将仓库根目录下的 chatatomic_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:用户登录

登录鉴权后才能正常使用组件的功能。调用 LoginStorelogin 接口,传入上文获取的 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) {
// 初始化失败
}
}
)

集成 TUIKit(旧架构)

版本说明
TUIKit(旧架构)为历史版本,目前已不再新增功能并逐步停止维护,主要面向存量项目继续使用。若您是新接入的项目,建议优先按上文「集成 TUIKit」章节进行集成,以获得更现代的架构、更低的接入成本与持续的功能更新。
TUIKit 新架构的主要优势

新架构
旧架构
开发语言
基于 Kotlin,借力协程与空安全,语法更简洁、更易维护
以 Java 为主
架构与自定义
界面与数据解耦,界面自定义更灵活、更安全
界面与数据耦合较高
主题与语言切换
主题、语言支持动态切换,无需重启应用
主题、语言切换需重启应用
性能与体验
动画更流畅,卡顿更少
受旧架构限制,流畅性弱于新架构
功能演进
持续支持新功能
仅维护,不再新增功能
TUIKit 旧版包含两套 UI 风格:经典版 UI(类微信 UI,自 5.7.1435 起支持)与 简约版 UI(类 WhatsApp UI,自 6.9.3557 起支持);二者不可混用,集成多个组件时需统一选择同一套 UI。各界面库功能介绍详见 TUIKit 界面库介绍
消息引用与回复功能的版本兼容性:
自 9.0.7652 版本起:
消息引用(Quote)改用 IMSDK 原生引用能力实现,与旧版本引用消息格式不兼容。新旧版本互发的引用消息无法正确解析引用内容,请将收发双方统一升级至 9.0.7652 及以上版本。
消息回复(Reply)功能已下线,相关接口与 UI 入口不再提供,如业务有相关需求,可参考旧版本 TUIKit 自行实现。
两者区别:引用是发送新消息时附带一条历史消息的摘要卡片,点击可跳转原消息(一问一答);回复是在某条消息下追加评论并聚合成回复列表(评论区式)。
1. 从 GitHub 下载 Android TUIKit 源码,将 TUIKit 目录复制到您的工程目录下:

2. 根据实际业务需求在 settings.gradle 中添加对应的 TUI 组件。TUI 组件之间相互独立,添加或删除均不影响工程编译。
说明:
TUIKit 可以放在任何位置,只要在 settings.gradle 中正确设置相对路径即可。
// 引入上层应用模块
include ':app'

// 引入内部组件通信模块 (必要模块)
include ':tuicore'
project(':tuicore').projectDir = new File(settingsDir, '../TUIKit/TUICore/tuicore')

// 引入 IM 组件公共模块(必要模块)
include ':timcommon'
project(':timcommon').projectDir = new File(settingsDir, '../TUIKit/TIMCommon/timcommon')

// 引入聊天功能模块 (基础功能模块)
include ':tuichat'
project(':tuichat').projectDir = new File(settingsDir, '../TUIKit/TUIChat/tuichat')

// 引入关系链功能模块 (基础功能模块)
include ':tuicontact'
project(':tuicontact').projectDir = new File(settingsDir, '../TUIKit/TUIContact/tuicontact')

// 引入会话功能模块 (基础功能模块)
include ':tuiconversation'
project(':tuiconversation').projectDir = new File(settingsDir, '../TUIKit/TUIConversation/tuiconversation')

// 引入搜索功能模块(需要购买旗舰版或企业版套餐)
include ':tuisearch'
project(':tuisearch').projectDir = new File(settingsDir, '../TUIKit/TUISearch/tuisearch')

// 引入社群话题功能模块(需要购买旗舰版或企业版套餐)
include ':tuicommunity'
project(':tuicommunity').projectDir = new File(settingsDir, '../TUIKit/TUICommunity/tuicommunity')

// 引入音视频通话模块依赖库
include ':atomic_x'
project(':atomic_x').projectDir = new File(settingsDir, '../TUIKit/atomic_x')

// 引入音视频通话功能模块
include ':tuicallkit-kt'
project(':tuicallkit-kt').projectDir = new File(settingsDir, '../TUIKit/TUICallKit/tuicallkit-kt')

// 引入视频会议模块
include ':tuiroomkit'
project(':tuiroomkit').projectDir = new File(settingsDir, '../TUIKit/TUIRoomKit/tuiroomkit')

// 引入语音转文字插件,从 7.5 版本开始支持
include ':tuivoicetotextplugin'
project(':tuivoicetotextplugin').projectDir = new File(settingsDir, '../TUIKit/TUIVoiceToTextPlugin/tuivoicetotextplugin')

// 引入聊天消息翻译插件,从 7.2 版本开始支持(需单独购买翻译插件)
include ':tuitranslationplugin'
project(':tuitranslationplugin').projectDir = new File(settingsDir, '../TUIKit/TUITranslationPlugin/tuitranslationplugin')

// 引入表情回应插件,从 7.8 版本开始支持(需要购买旗舰版或企业版套餐)
include ':tuiemojiplugin'
project(':tuiemojiplugin').projectDir = new File(settingsDir, '../TUIKit/TUIEmojiPlugin/tuiemojiplugin')
3. 在 app 模块的 build.gradle 中添加下列依赖:
dependencies {
api project(':tuiconversation')
api project(':tuicontact')
api project(':tuichat')
api project(':tuisearch')
api project(':tuicommunity')
api project(':tuicallkit-kt')
api project(':tuiroomkit')
// 集成语音转文字插件,从 7.5 版本开始支持
api project(':tuivoicetotextplugin')
// 集成翻译插件,从 7.2 版本开始支持(需单独购买翻译插件)
api project(':tuitranslationplugin')
// 集成表情回应插件,从 7.8 版本开始支持(需要购买旗舰版或企业版套餐)
api project(':tuiemojiplugin')
// 集成群接龙插件,从 7.1 版本开始支持
api "com.tencent.imsdk:tuigroupnote-plugin:9.0.7652"
// 集成群投票插件,从 7.1 版本开始支持
api "com.tencent.imsdk:tuipoll-plugin:9.0.7652"
// 集成会话分组插件,从 7.3 版本开始支持
api "com.tencent.imsdk:tuiconversationgroup-plugin:9.0.7652"
// 集成会话标记插件,从 7.3 版本开始支持
api "com.tencent.imsdk:tuiconversationmark-plugin:9.0.7652"
// 集成消息推送插件,从 7.6 版本开始支持
api 'com.tencent.timpush:timpush:8.9.7537'
// 按需集成对应厂商推送包
api 'com.tencent.timpush:fcm:8.9.7537'
api 'com.tencent.timpush:xiaomi:8.9.7537'
api 'com.tencent.timpush:meizu:8.9.7537'
api 'com.tencent.timpush:oppo:8.9.7537'
api 'com.tencent.timpush:vivo:8.9.7537'
api 'com.tencent.timpush:huawei:8.9.7537'
api 'com.tencent.timpush:honor:8.9.7537'
}
4. 在 app 目录下找到 AndroidManifest.xml 文件,在 application 节点中添加 tools:replace="android:allowBackup",覆盖组件内的设置,使用自己的设置。
// app/src/main/AndroidManifest.xml
<application
android:name=".BaseApplication"
android:allowBackup="false"
android:icon="@drawable/app_ic_launcher"
android:label="@string/app_name"
android:largeHeap="true"
android:theme="@style/AppTheme"
tools:replace="android:allowBackup">
5. 添加 maven 仓库。
Gradle 7.0 及以上(推荐方式)
Gradle 7.0 以下
Groovy DSL
Kotlin DSL
// settings.gradle
pluginManagement {
repositories {
google()
mavenCentral()
gradlePluginPortal()
maven { url "https://mirrors.tencent.com/nexus/repository/maven-public" }
maven { url "https://developer.huawei.com/repo" }
maven { url "https://developer.hihonor.com/repo" }
}
}
dependencyResolutionManagement {
repositories {
mavenCentral()
maven { url "https://mirrors.tencent.com/nexus/repository/maven-public/" }
maven { url "https://mirrors.tencent.com/repository/maven/liteavsdk/" }
maven { url "https://developer.huawei.com/repo/" }
maven { url "https://developer.hihonor.com/repo" }
}
}
// settings.gradle.kts
pluginManagement {
repositories {
google()
mavenCentral()
gradlePluginPortal()
maven { url = uri("https://mirrors.tencent.com/nexus/repository/maven-public") }
maven { url = uri("https://developer.huawei.com/repo") }
maven { url = uri("https://developer.hihonor.com/repo") }
}
}
dependencyResolutionManagement {
repositories {
mavenCentral()
maven { url = uri("https://mirrors.tencent.com/nexus/repository/maven-public") }
maven { url = uri("https://mirrors.tencent.com/repository/maven/liteavsdk") }
maven { url = uri("https://developer.huawei.com/repo") }
maven { url = uri("https://developer.hihonor.com/repo") }
}
}
Groovy DSL
Kotlin DSL
// project root build.gradle
buildscript {
repositories {
google()
mavenCentral()
maven { url "https://mirrors.tencent.com/nexus/repository/maven-public" }
maven { url "https://developer.huawei.com/repo" }
maven { url "https://developer.hihonor.com/repo" }
}
}
allprojects {
repositories {
google()
mavenCentral()
maven { url "https://mirrors.tencent.com/nexus/repository/maven-public/" }
maven { url "https://mirrors.tencent.com/repository/maven/liteavsdk/" }
maven { url "https://developer.huawei.com/repo/" }
maven { url "https://developer.hihonor.com/repo" }
}
}
// project root build.gradle.kts
buildscript {
repositories {
google()
mavenCentral()
maven { url = uri("https://mirrors.tencent.com/nexus/repository/maven-public") }
maven { url = uri("https://developer.huawei.com/repo") }
maven { url = uri("https://developer.hihonor.com/repo") }
}
}
allprojects {
repositories {
google()
mavenCentral()
maven { url = uri("https://mirrors.tencent.com/nexus/repository/maven-public") }
maven { url = uri("https://mirrors.tencent.com/repository/maven/liteavsdk") }
maven { url = uri("https://developer.huawei.com/repo") }
maven { url = uri("https://developer.hihonor.com/repo") }
}
}
6. 
配置 Kotlin 支持(可选)
​​
​如果您的项目已是 Kotlin 工程​:可跳过此步。
​如果您的项目尚未配置 Kotlin​:请添加对应版本的 Kotlin Gradle 插件:
注意:
若需添加 Kotlin Gradle 插件,$kotlin_version 请填入具体版本号,并确保其与您项目的 Android Gradle 插件版本兼容(如 $kotlin_version 设置为 1.9.0 ,对应的 Android Gradle 插件版本是 8.6.0)。可以参见 Kotlin-Gradle 插件兼容性。
// project root build.gradle
buildscript {
dependencies {
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
}
}
7. 配置混淆规则。
在您的 app/proguard-rules.pro 文件中添加以下混淆规则:
-dontshrink
-dontoptimize
-keep class com.tencent.qcloud.** { *; }
-keep class com.tencent.imsdk.** { *; }
-keep class * implements com.tencent.qcloud.tuicore.interfaces.TUIInitializer {}
8. Android Studio 中点击 File > Sync Project with Gradle Files 集成组件。
说明:
使用本地集成方案时,如需升级时需要从 GitHub 获取最新的组件代码,覆盖您本地项目的 TUIKit 目录。
当私有化修改和远端有冲突时,需要手动合并,处理冲突。
源码集成 TUIKit 时,默认会集成两套版本 UI 组件。
经典版和简约版 UI 不能混用,集成多个组件时,您必须同时全部选择经典版 UI 或简约版 UI。例如,经典版 TUIChat 组件必须与经典版 TUIConversationTUIContact 组件搭配使用。同理,简约版 TUIChat 组件必须与简约版 TUIConversationTUIContact 组件搭配使用。

接入步骤

常用的聊天软件都是由会话列表、聊天窗口、好友列表、音视频通话等几个基本的界面组成,参考下面步骤,您仅需几行代码即可在项目中快速搭建这些 UI 界面。 实操教学视频请参见:极速集成 TUIKit(Android)

步骤1:配置用户鉴权

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


步骤2:用户登录

登录鉴权后才能正常使用组件的功能。您可以调用 login 接口,传入上文获取的 sdkAppID、 userSig 用于登录鉴权:
TUILogin.login(context, sdkAppID, userID, userSig, new TUICallback() {
@Override
public void onSuccess() {
// 登录成功,可跳转聊天或会话页
}
@Override
public void onError(final int code, final String desc) {
// 登录失败,可弹框报错
}
});
注意:
在正式的生产环境中,建议在您的服务端生成 UserSig,在需要 UserSig 时由您的 App 向业务服务器发起请求获取动态 UserSig 来进行鉴权。详见 服务端生成 UserSig

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

会话列表只需要创建 TUIConversationFragment 对象加入到自己的布局即可。会话列表会从数据库中读取最近聊天记录,当用户点击聊天记录时,TUIConversationFragment 会默认跳转到聊天界面。
在您的 Activity 中执行如下代码:
经典版
简约版
TUIConversationFragment conversationFragment = new TUIConversationFragment();
// fragment_container 为您的布局中容纳会话列表 Fragment 的 FrameLayout
getSupportFragmentManager().beginTransaction()
.add(R.id.fragment_container, conversationFragment).commitAllowingStateLoss();
TUIConversationMinimalistFragment conversationFragment = new TUIConversationMinimalistFragment();
// fragment_container 为您的布局中容纳会话列表 Fragment 的 FrameLayout
getSupportFragmentManager().beginTransaction()
.add(R.id.fragment_container, conversationFragment).commitAllowingStateLoss();

步骤4:构建聊天界面

聊天界面用于展示和发送消息。TUIKit 提供两种集成方式:
使用预置的 Activity (推荐)
自定义 Activity 嵌入 Fragment
TUIKit 已经提供了完整的聊天 Activity,可以直接启动 :
经典版
简约版
Bundle param = new Bundle();
param.putInt(TUIConstants.TUIChat.CHAT_TYPE, isGroup ? V2TIMConversation.V2TIM_GROUP : V2TIMConversation.V2TIM_C2C);
// 如果是 C2C 聊天,chatID 是对方的 UserID,如果是 Group 聊天,chatID 是 GroupID
param.putString(TUIConstants.TUIChat.CHAT_ID, chatID);
if (isGroup) {
TUICore.startActivity("TUIGroupChatActivity", param);
} else {
TUICore.startActivity("TUIC2CChatActivity", param);
}
Bundle param = new Bundle();
param.putInt(TUIConstants.TUIChat.CHAT_TYPE, isGroup ? V2TIMConversation.V2TIM_GROUP : V2TIMConversation.V2TIM_C2C);
// 如果是 C2C 聊天,chatID 是对方的 UserID,如果是 Group 聊天,chatID 是 GroupID
param.putString(TUIConstants.TUIChat.CHAT_ID, chatID);
if (isGroup) {
TUICore.startActivity("TUIGroupChatMinimalistActivity", param);
} else {
TUICore.startActivity("TUIC2CChatMinimalistActivity", param);
}
如果需要自定义标题栏或其他 UI,可以创建自己的 Activity,在您的 Activity 中执行如下代码:
经典版
简约版
Fragment fragment;
// 如果是 C2C 聊天,chatID 是对方的 UserID,如果是 Group 聊天,chatID 是 GroupID
if (isGroup) {
GroupChatInfo groupChatInfo = new GroupChatInfo();
groupChatInfo.setId(chatID);
TUIGroupChatFragment tuiGroupChatFragment = new TUIGroupChatFragment();
tuiGroupChatFragment.setChatInfo(groupChatInfo);
fragment = tuiGroupChatFragment;
} else {
C2CChatInfo c2cChatInfo = new C2CChatInfo();
c2cChatInfo.setId(chatID);
TUIC2CChatFragment tuic2CChatFragment = new TUIC2CChatFragment();
tuic2CChatFragment.setChatInfo(c2cChatInfo);
fragment = tuic2CChatFragment;
}
// chat_fragment_container 为您的布局中容纳聊天页 Fragment 的 FrameLayout
getSupportFragmentManager().beginTransaction()
.add(R.id.chat_fragment_container, fragment).commitAllowingStateLoss();
Fragment fragment;
// 如果是 C2C 聊天,chatID 是对方的 UserID,如果是 Group 聊天,chatID 是 GroupID
if (isGroup) {
GroupChatInfo groupChatInfo = new GroupChatInfo();
groupChatInfo.setId(chatID);
TUIGroupChatMinimalistFragment tuiGroupChatFragment = new TUIGroupChatMinimalistFragment();
tuiGroupChatFragment.setChatInfo(groupChatInfo);
fragment = tuiGroupChatFragment;
} else {
C2CChatInfo c2cChatInfo = new C2CChatInfo();
c2cChatInfo.setId(chatID);
TUIC2CChatMinimalistFragment tuic2CChatFragment = new TUIC2CChatMinimalistFragment();
tuic2CChatFragment.setChatInfo(c2cChatInfo);
fragment = tuic2CChatFragment;
}
// chat_fragment_container 为您的布局中容纳聊天页 Fragment 的 FrameLayout
getSupportFragmentManager().beginTransaction()
.add(R.id.chat_fragment_container, fragment).commitAllowingStateLoss();

步骤5:构建联系人界面

联系人界面展示用户的好友列表、群组列表、黑名单列表和新好友申请。
联系人列表界面不需要其它依赖,只需创建对象并显示出来即可。点击联系人,默认会跳转到联系人详情界面。
在您的 Activity 中执行如下代码:
经典版
简约版
TUIContactFragment contactFragment = new TUIContactFragment();
// fragment_container 为您的布局中容纳联系人列表 Fragment 的 FrameLayout
getSupportFragmentManager().beginTransaction()
.add(R.id.fragment_container, contactFragment).commitAllowingStateLoss();
TUIContactMinimalistFragment contactFragment = new TUIContactMinimalistFragment();
// fragment_container 为您的布局中容纳联系人列表 Fragment 的 FrameLayout
getSupportFragmentManager().beginTransaction()
.add(R.id.fragment_container, contactFragment).commitAllowingStateLoss();

步骤6:构建音视频通话功能 (可选)

TUI 组件支持在聊天界面对用户发起音视频通话,仅需要简单几步就可以快速集成:
视频通话
语音通话






1. 开通音视频服务
1.1 登录 即时通信 IM 控制台 ,单击目标应用卡片,进入应用的基础配置页面。
1.2 在开通腾讯实时音视频服务功能区,单击免费体验即可开通 TUICallKit 的 7 天免费试用服务。
1.3 在弹出的开通实时音视频 TRTC 服务对话框中,单击确认,系统将为您在 实时音视频控制台 创建一个与当前 IM 应用相同 SDKAppID 的实时音视频应用,二者账号与鉴权可复用。
2. 集成 TUICallKit 组件
在 settings.gradle 中添加 tuicallkit 组件,设置正确的相对路径:
include ':atomic_x'
project(':atomic_x').projectDir = new File(settingsDir, '../TUIKit/atomic_x')

include ':tuicallkit-kt'
project(':tuicallkit-kt').projectDir = new File(settingsDir, '../TUIKit/TUICallKit/tuicallkit-kt')
在 app 模块的 build.gradle 文件中添加对 TUICallKit 的依赖:
api project(':tuicallkit-kt')
3. 发起和接收视频或语音通话
消息页发起通话
联系人页发起通话






集成 TUICallKit 组件后,聊天界面和联系人资料界面默认会显示 “视频通话” 和 “语音通话” 两个按钮,当用户点击按钮时,TUIKit 会自动展示通话邀请 UI,并给对方发起通话邀请请求。
当用户在线并且应用在前台收到通话邀请时,TUIKit 会自动展示通话接收 UI,用户可以选择同意或者拒绝通话。
当用户离线收到通话邀请时,如需唤起 App 通话,需要使用离线推送能力。离线推送的实现请参考下一步。
4. 添加离线推送:
实现音视频通话的离线推送,请参考以下几个步骤:
4.1 配置 App 的 推送功能
4.2 集成 TUICallKit 组件。
4.3 通过 TUICallKit 发起通话邀请的时候,默认会生成一条离线推送消息。
说明:
配置完成后,当单击接收到的音视频通话离线推送通知时, TUICallKit 会自动拉起音视频通话邀请界面
5. 附加增值能力
集成 TUIChat 和 TUICallKit 的组件后,在聊天界面发送语音消息时,即可录制带 AI 降噪和自动增益的语音消息。该功能需要购买 音视频通话能力 进阶版及以上套餐,仅 IMSDK 7.0 及以上版本支持。当套餐过期后,录制语音消息会切换到系统 API 进行录音。
下面是使用两台华为 P10 同时录制的语音消息对比:


步骤7:构建多人音视频功能 (可选)

TUI 组件支持在聊天界面对用户发起多人音视频,仅需要简单几步就可以快速集成:

1. 开通音视频服务
1.1 登录 即时通信 IM 控制台,单击目标应用卡片,进入应用的基础配置页面。
1.2 找到含 UI 低代码场景方案功能区,单击卡片下方的多人音视频(TUIRoomKit) > 免费体验。
1.3 在弹窗中单击免费试用7天,即可成功开通多人音视频免费体验版。开通完成后即可参见 集成指引 进行集成。
2. 集成 TUIRoomKit 组件
在 settings.gradle 中添加 tuiroomkit 组件,设置正确的相对路径:
include ':tuiroomkit'
project(':tuiroomkit').projectDir = new File(settingsDir, '../TUIKit/TUIRoomKit/tuiroomkit')
在 app 模块的 build.gradle 文件中添加对 TUIRoomKit 的依赖:
api project(':tuiroomkit')
3. 发起多人音视频会议
集成 TUIRoomKit 组件后,聊天界面默认会出现 “快速会议” 按钮,当用户点击按钮时,TUIKit 会自动发起会议,并在聊天记录中展示一条会议邀请卡片。


常见问题

音视频常见问题

通话邀请的超时时间默认是多久?
通话邀请的默认超时时间是 30 秒。
在邀请超时时间内,被邀请者如果离线再上线,能否立即收到邀请?
如果是单聊通话邀请,被邀请者离线再上线可以收到通话邀请,TUIKit 内部会自动唤起通话邀请界面。
如果是群聊通话邀请,被邀请者离线再上线后会自动拉取最近 30 秒内的邀请,TUIKit 会自动唤起群通话界面。

Android Studio 集成常见问题

提示 "Manifest merger failed : Attribute application@allowBackup value=(true) from AndroidManifest.xml" 如何处理?
IM SDK 中默认 allowBackup 的值为 false ,表示关闭应用的备份和恢复功能。
您可以在您的 AndroidManifest.xml 文件中删除 allowBackup 属性,表示关闭备份和恢复功能;也可以在 AndroidManifest.xml 文件的 application 节点中添加 tools:replace="android:allowBackup" 表示覆盖 IM SDK 的设置,使用您自己的设置。
// app/src/main/AndroidManifest.xml
<application
android:name=".BaseApplication"
android:allowBackup="false"
android:icon="@drawable/app_ic_launcher"
android:label="@string/app_name"
android:largeHeap="true"
android:theme="@style/AppTheme"
tools:replace="android:allowBackup">
提示 "Plugin with id 'kotlin-android' not found." 如何处理?
因为 TUIChat 组件使用了 Kotlin 代码,所以需要添加 Kotlin 构建插件。请参考 配置 Kotlin
复制 TUIKit 代码到自己的工程的模块中,使用时发生空指针等异常问题?
当您将 TUIKit 的某个模块代码复制到自己工程的某个模块目录下时,除了需要迁移 TUIKit 模块的 Manifest 文件内容外,还必须在目标模块的 build.gradle 文件中添加如下必要的依赖。这一步骤是确保 TUIKit 组件能够正确初始化的关键。如果忽略这些依赖,可能会导致空指针等异常问题。
dependencies {
annotationProcessor 'com.google.auto.service:auto-service:1.1.1'
}

其他常见问题

表情包的使用
为了尊重版权,IM Demo/TUIKit 工程中默认不包含大表情元素切图。正式上线商用前请您替换为自己设计或拥有版权的其他表情包。下图所示默认的小黄脸表情包版权归腾讯云所有,可有偿授权使用,如需获得授权,您可以通过升级至 IM 企业版套餐 免费使用该表情包。




联系我们

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