Android

最近更新时间:2026-02-10 17:24:49

我的收藏
TUIRoomKit 是腾讯云提供的一站式多人音视频房间解决方案,集成了完整的 UI 组件和核心功能。通过本文档,开发者可以快速了解如何将 TUIRoomKit 集成到项目中,实现多人音视频房间功能。本文还将详细介绍如何快速替换图片资源、本地化文案等个性化配置,帮助开发者打造符合品牌特色的音视频应用。
房间准备页
房间主页
成员管理










前提条件

开通服务

请参考 开通服务 领取 TUIRoomKit 体验版,并在 应用管理 页面获取以下信息:
SDKAppID:应用标识(必填),腾讯云基于 SDKAppID 完成计费统计。
SDKSecretKey:应用密钥,用于初始化配置文件的密钥信息。

环境准备

Android Studio Arctic Fox (2020.3.1) 及以上版本。
Gradle 7.0 及以上的版本。
Android 5.0 及以上的手机设备。

快速接入

步骤1:下载 TUIRoomKit 组件

GitHub 中克隆/下载代码,然后将 room 子目录和 atomic_x 子目录拷贝到您当前 Android 项目的 app 文件夹同级目录中。


步骤2:工程配置

1. 导入 TUIRoomKit 组件

在工程根目录下的 settings.gradle.ktssettings.gradle 文件中,增加以下代码以导入 tuiroomkit 组件。
settings.gradle.kts
settings.gradle
include(":tuiroomkit")
project(":tuiroomkit").projectDir = File(settingsDir, "room/tuiroomkit")

include(":atomic")
project(":atomic").projectDir = File(settingsDir, "atomic_x")
include ':tuiroomkit'
project(':tuiroomkit').projectDir = new File(settingsDir, "room/tuiroomkit")

include(":atomic")
project(':atomic').projectDir = new File(settingsDir, "atomic_x")

2. 添加组件依赖

app 目录下找到 build.gradle.kts(或 build.gradle)文件,并在文件中增加以下代码,该步骤的作用是声明当前 App 对新加入的 tuiroomkit 组件的依赖。
build.gradle.kts
build.gradle
dependencies {
// 添加 tuiroomkit 依赖
api(project(":tuiroomkit"))
}
dependencies {
// 添加 tuiroomkit 依赖
api project(':tuiroomkit')
}
说明:
TUIRoomKit 内部已默认依赖 TRTC SDK、IM SDK 等公共库,您无需单独配置。

3. 配置混淆规则

由于 SDK 内部使用了 Java 反射,请在 proguard-rules.pro 文件中添加以下代码,将相关类加入不混淆名单,以确保功能正常运行。
-keep class com.tencent.** { *; }
-keep class com.tencent.beacon.** { *; }
-keep class com.tencent.cloud.iai.lib.** { *; }
-keep class com.tencent.qimei.** { *; }
-keep class com.tencent.xmagic.** { *; }
-keep class com.tcmediax.** { *; }

# Google 序列化/反序列化框架 Gson 库相关混淆
-keep class com.google.gson.** { *; }


4. 修改 AndroidManifest.xml

为了防止编译时AndroidManifest合并过程中产生属性冲突,您需要在 app/src/main/AndroidManifest.xml 文件的 <application> 节点中,添加 tools:replace="android:allowBackup"android:allowBackup="false",用以覆盖组件内的设置。
<application
...
// 添加如下配置覆盖 依赖的 sdk 中的配置
android:allowBackup="false"
tools:replace="android:allowBackup">

5. 完成项目同步

在您完成上述步骤后,通常情况下 Android Studio 会自动为您弹出 Sync Now 按钮,您需要点击该同步按钮完成项目的同步,若 IDE 没有自动弹出同步按钮,请您手动点击工具栏中的同步按钮进行项目的同步,同步后 IDE 会完成项目的构建配置和索引等工作,您就可以在您的项目中正常使用 TUIRoomKit 组件了。


步骤3:登录

代码集成完成后,您需要完成登录。这是使用 TUIRoomKit 的关键步骤,因为只有在登录成功后才能正常使用 TUIRoomKit 的各项功能,故请您耐心检查相关参数是否配置正确:
说明:
在示例代码中,直接进行了登录接口的调用。但在实际项目场景下,强烈推荐您在完成自己的用户身份验证等相关登录操作后,再调用 AtomicXCore 的登录服务。这样可以避免因过早调用登录服务,导致业务逻辑混乱或数据不一致的问题,同时也能更好地适配您项目中现有的用户管理和权限控制体系。
Kotlin
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import io.trtc.tuikit.atomicxcore.api.login.LoginStore
import io.trtc.tuikit.atomicxcore.api.CompletionHandler
import android.util.Log


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


LoginStore.shared.login(
this, // context
1400000001, // 替换为项目的 sdkAppID
"test_001", // 替换为项目的 userID
"xxxxxxxxxxx", // 替换为项目的 userSig
object : CompletionHandler {
override fun onSuccess() {
// 登录成功处理
Log.d("Login", "login success");
}


override fun onFailure(code: Int, desc: String) {
// 登录失败处理
Log.e("Login", "login failed, code: $code, error: $desc");
}
}
)
}
}

登录接口参数说明:
参数
类型
说明
sdkAppID
Int32
控制台 获取,通常是以 140160 开头的 10 位整数。
userID
String
当前用户的唯一 ID,仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突,请勿使用 1123 等简单 ID
userSig
String
用于腾讯云鉴权的票据。更多信息请参见 如何计算及使用 UserSig
【注意事项】
开发环境:可以采用本地 GenerateTestUserSig.genTestSig 函数生成 userSig 或者通过 UserSig 辅助工具 生成临时的 userSig。
生产环境:为了防止密钥泄露,请务必采用服务端生成 userSig 的方式。详细信息请参考 服务端生成 UserSig

步骤4:设置头像和昵称

首次登录的用户没有头像和昵称信息,需要通过 LoginStoresetSelfInfo接口设置个人信息:
import android.util.Log
import io.trtc.tuikit.atomicxcore.api.CompletionHandler
import io.trtc.tuikit.atomicxcore.api.login.LoginStore
import io.trtc.tuikit.atomicxcore.api.login.UserProfile

private val TAG = "Test"

fun setSelfInfo() {
val userProfile = UserProfile(
userID = "test_001", // 您已经登录的userID
nickname = "tom", // 设置昵称
avatarURL = "http://xxx.png" // 设置头像URL
)

LoginStore.shared.setSelfInfo(userProfile, object : CompletionHandler {
override fun onSuccess() {
Log.d(TAG, "setSelfInfo success")
}

override fun onFailure(code: Int, desc: String) {
Log.e(TAG, "setSelfInfo failed code:$code, message:$desc")
}
})
}
setSelfInfo接口参数说明:
参数
类型
必填
说明
userProfile
UserProfile
个人用户信息核心模型,包含:
userID:要设置用户信息的用户 ID。
nickname:昵称信息。
avatarURL:头像链接。
completion
CompletionHandler
设置个人信息接口的结果回调。若失败会返回错误码和错误信息。

步骤5:创建房间

TUIRoomKit 组件中,RoomMainView是集成了完整的多人音视频房间功能的核心界面,以下将对开发者演示如何以房主身份将RoomMainView嵌入到应用中。

实现方式:

1. 加载创建视图页面:懒加载方式实例化 RoomMainView
2. 构造进房的配置项:进入房间后是否需要自动打开音视频设备的配置项。
3. 初始化房间主页面:通过房主身份初始化房间主页面。
4. 将视图添加到视图 Activity:在ActivityonCreate 方法中,将 RoomMainView 添加到Activity中,并使用布局使其充满整个视图区域。

示例代码:

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.trtc.uikit.roomkit.view.RoomMainView
import io.trtc.tuikit.atomicxcore.api.room.CreateRoomOptions

// MainActivity 代表您加载房间主页面的 Activity
class MainActivity : AppCompatActivity() {

// 1 加载创建视图页面
private val roomView: RoomMainView by lazy {
RoomMainView(this).apply {
// 2 构造进房的配置项
val config = RoomMainView.ConnectConfig(
autoEnableMicrophone = true, // 进房后是否自动开启麦克风
autoEnableCamera = true, // 进房后是否自动开启摄像头
autoEnableSpeaker = true // 进房后是否自动开启扬声器
)

val options = CreateRoomOptions(roomName = "roomName") // 房间名称
val behavior = RoomMainView.RoomBehavior.Create(options)
// 3 初始化房间主页面
init("roomID", behavior, config)
}
}

override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// 4. 将视图添加到视图Activity
setContentView(roomView)
}
}

RoomMainView init 函数参数详细说明
参数
类型
说明
roomID
String
字符串类型的房间唯一标识符。
限制长度为 0-48 字节。
建议仅包含数字、英文字母(区分大小写)、下划线(_)和连字符(-)。避免使用空格和中文字符。
behavior
RoomBehavior
房间主页面初始化来源。
Create: 房主身份创建房间。此方式需要构造创建房间配置项,关于 CreateRoomOptions 的详细用法请参考:CreateRoomOptions 结构体详细说明
Join:参与者身份加入房间。
config
ConnectConfig
进房后音视频设备控制的配置项。

ConnectConfig 参数详细说明
参数
类型
说明
autoEnableMicrophone
Boolean
进房后是否自动开启麦克风
true:自动开启 (默认值)。
false:不自动开启。
autoEnableCamera
Boolean
进房后是否自动开启摄像头。
true:自动开启 (默认值)。
false:不自动开启。
autoEnableSpeaker
Boolean
进房后是否自动开启扬声器。
true:自动开启 (默认值)。
false:不自动开启。
CreateRoomOptions 结构体详细说明
参数名
类型
必填
说明
roomName
String
房间名称,可以不设置,默认为空字符串。
限制长度为 0-60 字节。
支持中英文、数字、特殊字符。
password
String
房间密码,空字符串 "" 通常表示该房间不设密码。
限制长度为 0-32 字节。
推荐使用 4-8 位纯数字,方便移动端输入。设置后,其他用户加入房间时需输入密码。建议不要存储明文敏感信息。
isAllMicrophoneDisabled
Boolean
是否全员禁止打开麦克风。开启后,除房主/管理员外,普通参与者默认禁止打开麦克风。
true:禁止。
false:取消禁止 (默认值)。
isAllCameraDisabled
Boolean
是否全员禁止打开摄像头。开启后,除房主/管理员外,普通参与者默认禁止打开摄像头。
true:禁止。
false:取消禁止(默认值)。
isAllScreenShareDisabled
Boolean
是否全员禁止发起屏幕共享。开启后,仅房主/管理员可进行屏幕共享。
true:禁止。
false:取消禁止(默认值)。
isAllMessageDisabled
Boolean
是否全员禁止发送聊天消息(禁言)。开启后,普通参与者无法在房间内发送文字消息。
true:禁止。
false:取消禁止(默认值)。

步骤6:加入房间

以下示例将向开发者演示如何以参与者身份将RoomMainView嵌入到应用中。

实现方式:

1. 加载创建视图页面:懒加载方式实例化 RoomMainView
2. 构造进房的配置项:进入房间后是否需要自动打开音视频设备的配置项。
3. 初始化房间主页面:通过参与者身份初始化房间主页面。
4. 将视图添加到视图 Activity:在ActivityonCreate 方法中,将 RoomMainView 添加到Activity中,并使用布局使其充满整个视图区域。

代码示例:

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.trtc.uikit.roomkit.view.RoomMainView

// MainActivity 代表您加载房间主页面的 Activity
class MainActivity : AppCompatActivity() {

// 1 加载创建视图页面
private val roomView: RoomMainView by lazy {
RoomMainView(this).apply {
// 2 构造进房的配置项
val config = RoomMainView.ConnectConfig(
autoEnableMicrophone = true, // 进房后是否自动开启麦克风
autoEnableCamera = true, // 进房后是否自动开启摄像头
autoEnableSpeaker = true // 进房后是否自动开启扬声器
)

val behavior = RoomMainView.RoomBehavior.Join
// 3 初始化房间主页面
init("roomID", behavior, config)
}
}

override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// 4. 将视图添加到视图Activity
setContentView(roomView)
}
}

核心功能

接入RoomMainView代码后,开发者将得到一个完整的多人音视频页面,内部包含成员管理,音视频设备控制,房间信息展示等功能,这是 TUIRoomKit 组件的核心。




界面定制

RoomMainView房间主页面内功能丰富,可定制化度高,开发者可以根据实际产品需求,对 UI 进行定制化修改,以适配业务交互场景。以下将详细为开发者展示RoomMainView页面中视图组件,便于开发者快速修改。



RoomMainView中组件详细说明
组件
功能描述
定制化建议
房间主视图容器,负责协调各子组件的布局与数据流转。
可调整整体背景、安全区域适配、组件显隐逻辑。
顶部导航栏,包含房间信息、摄像头和声音控制、退出房间功能入口。
可替换图标、调整背景透明度、添加自定义按钮(例如录制、 窗口化)。
RoomView
视频流展示区域,采用瀑布流布局管理多个用户视频画面。
可修改布局算法(行列数、间距)、分页指示器样式、空状态视图。
单个视频流单元格挂件,承载用户视频画面与基本信息。
可自定义视频渲染层、用户信息面板(头像、徽章)、互动控件(语音波形)。
底部工具栏,集成麦克风、摄像头、成员管理操作按钮。
可重新排列按钮顺序、修改按钮样式(颜色、尺寸)、添加业务相关功能(例如屏幕分享、会中呼叫、美颜)。

图标定制

接入 TUIRoomKit组件后,开发者可以根据实际 UI 交互需求直接替换组件下的图标资源, 以适配开发者的业务场景。



常用的图片文件列表
图标
文件名
说明



roomkit_ic_camera_off.png
摄像头关闭图标



roomkit_ic_camera_on.png
摄像头开启图标



roomkit_ic_microphone_off.png
麦克风关闭图标



roomkit_ic_microphone_on.png
麦克风开启图标



roomkit_icon_user_room_manager.png
管理员身份标识图标



roomkit_ic_video_seat_owner.png
房主身份标识图标

文案定制

TUIRoomKit 使用 Android 通用的 XML 资源文件来管理 UI 所需的文案显示,您可以直接通过 XML 文件修改需要调整的文案:




常见问题

每次进房都需要调用登录吗?

不需要。通常您只需要完成一次 LoginStore.shared.login 调用即可,我们建议您将 LoginStore.shared.login
LoginStore.shared.logout 与自己的登录业务关联。

Android 14 以上机型切到后台后, 采集音视频无画面/无声音?

Android 14 及以上版本,应用在后台采集摄像头或麦克风数据时,必须启动前台服务并声明对应的服务类型,否则无法正常采集,解决方案可按照下面步骤:
1. AndroidManifest.xml 声明 FOREGROUND_SERVICEFOREGROUND_SERVICE_CAMERAFOREGROUND_SERVICE_MICROPHONE 权限和 service 声明。
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />

<service
android:name=".MediaCaptureService"
android:foregroundServiceType="camera|microphone" />
2. 在界面启动后开启后台采集服务。
import android.app.NotificationChannel
import android.app.NotificationManager
import android.app.Service
import android.content.Intent
import android.content.pm.ServiceInfo
import android.os.Bundle
import android.os.IBinder
import androidx.appcompat.app.AppCompatActivity
import androidx.core.app.NotificationCompat

class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
startForegroundService(Intent(this, MediaCaptureService::class.java))
}
}

class MediaCaptureService : Service() {
override fun onCreate() {
super.onCreate()
// 1. 创建通知渠道
val channel = NotificationChannel("media", "媒体采集", NotificationManager.IMPORTANCE_LOW)
getSystemService(NotificationManager::class.java).createNotificationChannel(channel)

// 2. 构建通知
val notification = NotificationCompat.Builder(this, "media")
.setContentTitle("音视频通话中")
.setSmallIcon(android.R.drawable.ic_menu_call)
.build()

// 3. 启动前台服务,指定 camera 和 microphone 类型(Android 14+ 必须)
startForeground(1, notification,
ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA or ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE)
}

override fun onBind(intent: Intent?): IBinder? = null
}