iOS

最近更新时间:2026-02-09 15:40:42

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










前提条件

开通服务

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

环境准备

在开始运行 Demo 之前,请确保您的开发环境满足以下要求:
Xcode:需使用 Xcode 15 或更高版本。
iOS 系统:支持 iOS 13.0 或更高版本的设备。
CocoaPods 环境:已安装 CocoaPods 环境。如果您尚未安装,请参见 CocoaPods官网安装,或按以下步骤操作:
使用 gem 安装 CocoaPods:在终端中执行 sudo gem install cocoapods 命令进行安装。
提示:
sudo gem install cocoapods 安装过程中可能需要输入电脑密码,按提示输入管理员密码即可。

快速接入

步骤1:集成 TUIRoomKit 组件

1. 添加 Pod 依赖:
若项目已有 Podfile 文件。
在您项目的 Podfile 文件中添加 pod 'TUIRoomKit' 依赖。例如:
target 'YourProjectTarget' do
# 其他已有的 Pod 依赖...
# 添加 pod 'TUIRoomKit' 依赖
pod 'TUIRoomKit'

end
若项目没有 Podfile 文件。
在终端中通过 cd 命令切换到您的 .xcodeproj 目录下,然后执行 pod init 命令创建 Podfile 文件,创建完成后,在您的 Podfile 文件中添加 pod 'TUIRoomKit' 依赖。例如:
// 如果您的项目目录是 /Users/yourusername/Projects/YourProject

// 1. cd 到您的.xcodeproj 工程目录下
cd /Users/yourusername/Projects/YourProject

// 2. 执行 pod init,此命令运行完后,会在您的工程目录下生成一个 Podfile 文件。
pod init

// 3. 在生成的 Podfile 文件中添加 pod 'TUIRoomKit' 依赖
target 'YourProjectTarget' do
# 添加 pod 'TUIRoomKit' 依赖
pod 'TUIRoomKit'

end
2. 安装组件
在终端中 cdPodfile 文件所在的目录,然后执行以下命令安装组件。
pod install

步骤2:工程配置

为了使用音视频功能,您的应用需要获取麦克风和摄像头的权限。请在应用的 Info.plist 文件中添加以下两项,并填写对应的使用说明,这些说明将在系统请求权限时向用户显示:
<key>NSCameraUsageDescription</key>
<string>TUIRoomKit需要访问您的相机权限</string>
<key>NSMicrophoneUsageDescription</key>
<string>TUIRoomKit需要访问您的麦克风权限</string>




步骤3:登录

代码集成完成后,需要完成登录操作,这是使用 TUIRoomKit 的关键步骤。只有在登录成功后,才能正常使用 TUIRoomKit 的各项功能,因此请仔细检查相关参数配置是否正确:
说明:
在示例代码中,登录操作是在 didFinishLaunchingWithOptions 方法内完成的。但在实际项目场景下,强烈推荐在完成自己的用户身份验证等相关登录操作后,再调用 AtomicXCore 的登录服务。这样可以避免因过早调用登录服务,导致业务逻辑混乱或数据不一致的问题,同时也能更好地适配您项目中现有的用户管理和权限控制体系。
Swift
import AtomicXCore

// AppDelegate.swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
LoginStore.shared.login(sdkAppID: 1400000001, // 替换为项目的 sdkAppID
userID: "test_001", // 替换为项目的 userID
userSig: "xxxxxxxxxxx") { result in // 替换为项目的 userSig
switch result {
case .success(let info):
debugPrint("login success")
case .failure(let error):
debugPrint("login failed code:\\(error.code), message:\\(error.message)")
}
}
return true
}
登录接口参数说明:
参数
类型
说明
sdkAppID
Int32
控制台 获取,通常是以 140160 开头的 10 位整数。
userID
String
当前用户的唯一 ID,仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突,请勿使用 1123 等简单 ID
userSig
String
用于腾讯云鉴权的票据。更多信息请参见 如何计算及使用 UserSig
【注意事项】
开发环境:可以采用本地 GenerateTestUserSig.genTestSig 函数生成 userSig 或者通过 UserSig 辅助工具 生成临时的 userSig。
生产环境:为了防止密钥泄露,请务必采用服务端生成 userSig 的方式。详细信息请参考 服务端生成 UserSig

步骤4:设置头像和昵称

首次登录的用户没有头像和昵称信息,需要通过 LoginStoresetSelfInfo接口设置个人信息:
import AtomicXCore

func setSelfInfo() {
let userProfile = UserProfile(userID: "test_001", // 您已经登录的userID
nickname: "tom", // 设置昵称
avatarURL: "http://xxx.png") // 设置头像URL
LoginStore.shared.setSelfInfo(userProfile: userProfile) { result in
switch result {
case .success():
debugPrint("setSelfInfo success")
case .failure(let error):
debugPrint("setSelfInfo failed code:\\(error.code), message:\\(error.message)")
}
}
}
setSelfInfo接口参数说明:
参数
类型
必填
说明
userProfile
UserProfile
个人用户信息核心模型,包含:
userID:要设置用户信息的用户 ID。
nickname:昵称信息。
avatarURL:头像链接。
completion
CompletionClosure
设置个人信息接口的结果回调。若失败会返回错误码和错误信息。

步骤5:创建房间

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

实现方式:

1. 遵守路由导航协议TUIRoomKit 内部使用 RouterContext 协议管理页面间的路由跳转。宿主视图控制器需要声明遵循该协议,以确保组件内部的导航操作(如结束房间、返回上一页)能够正确执行。
2. 懒加载创建视图页面:在控制器内部以懒加载方式实例化 RoomMainView,并为其设置 routerContext 属性。该属性使得视图能够通过协议方法调用宿主控制器的导航功能。
3. 构造进房的配置项:进入房间后是否需要自动打开音视频设备的配置项。
4. 初始化房间主页面:通过房主身份初始化房间主页面。
5. 将视图添加到控制器:在控制器的 viewDidLoad 方法中,将 RoomMainView 加入视图层级,并使用约束布局使其充满整个控制器视图区域。
说明:
TUIRoomKit 的内部页面跳转机制基于 UINavigationController 的标准导航方法(push/pop)实现。为确保页面路由功能正常工作,开发者的视图控制器必须作为 UINavigationController 的根视图控制器或位于其导航栈内。若未将控制器包装至 UINavigationController 中,SDK 内部的跳转操作将因缺少有效的导航上下文而失效,导致页面无法正常切换。

示例代码:

import UIKit
import TUIRoomKit
import SnapKit
import AtomicXCore

// YourMainViewController 代表您加载房间主页面的视图控制器

// 1. YourMainViewController 需要遵守 TUIRoomKit 组件中的 RouterContext 协议
class YourMainViewController: UIViewController, RouterContext {
// 2. 懒加载创建 TUIRoomKit 中的 RoomMainView 房间主页面
private lazy var mainView: RoomMainView = {
// 3. 构造进房的配置项
var config = ConnectConfig()
config.autoEnableCamera = true // 进房后是否自动开启摄像头
config.autoEnableMicrophone = true // 进房后是否自动开启麦克风
config.autoEnableSpeaker = true // 进房后是否自动开启扬声器
// 4 房主身份初始化房间主页面
var options = CreateRoomOptions()
options.roomName = "roomName" // 房间名称
let view = RoomMainView(roomID: "roomID", behavior: .create(options: options), config: config)
view.routerContext = self
return view
}()
public override func viewDidLoad() {
super.viewDidLoad()
// 5. 将 RoomMainView 对象 添加到视图控制器中
view.addSubview(mainView)
mainView.snp.makeConstraints { make in
make.edges.equalToSuperview()
}
}
}

RoomMainView 构造函数参数详细说明:

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

ConnectConfig 参数详细说明
参数
类型
说明
autoEnableMicrophone
Bool
进房后是否自动开启麦克风。
true: 自动开启 (默认值)。
false: 不自动开启。
autoEnableCamera
Bool
进房后是否自动开启摄像头。
true: 自动开启 (默认值)。
false: 不自动开启。
autoEnableSpeaker
Bool
进房后是否自动开启扬声器。
true: 自动开启 (默认值)。
false: 不自动开启。

步骤6:加入房间

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

实现方式:

1. 遵守路由导航协议TUIRoomKit 内部使用 RouterContext 协议管理页面间的路由跳转。宿主视图控制器需要声明遵循该协议,以确保组件内部的导航操作(如结束房间、返回上一页)能够正确执行。
2. 懒加载创建视图页面:在控制器内部以懒加载方式实例化 RoomMainView,并为其设置 routerContext 属性。该属性使得视图能够通过协议方法调用宿主控制器的导航功能。
3. 构造进房的配置项:进入房间后是否需要自动打开音视频设备的配置项。
4. 初始化房间主页面:通过参与者身份初始化房间主页面。
5. 将视图添加到控制器:在控制器的 viewDidLoad 方法中,将 RoomMainView 加入视图层级,并使用约束布局使其充满整个控制器视图区域。

代码示例:

import UIKit
import TUIRoomKit
import SnapKit
import AtomicXCore
// YourMainViewController 代表您加载房间主页面的视图控制器

// 1. YourMainViewController 需要遵守 TUIRoomKit 组件中的 RouterContext 协议
class YourMainViewController: UIViewController, RouterContext {
// 2. 懒加载创建 TUIRoomKit 中的 RoomMainView 房间主页面
private lazy var mainView: RoomMainView = {
// 3. 构造进房的配置项
var config = ConnectConfig()
config.autoEnableCamera = true // 进房后是否自动开启摄像头
config.autoEnableMicrophone = true // 进房后是否自动开启麦克风
config.autoEnableSpeaker = true // 进房后是否自动开启扬声器
// 4. 参与者身份初始化房间主页面
let view = RoomMainView(roomID: "roomID", behavior: .join, config: config)
view.routerContext = self
return view
}()
public override func viewDidLoad() {
super.viewDidLoad()
// 5. 将 RoomMainView 对象 添加到视图控制器中
view.addSubview(mainView)
mainView.snp.makeConstraints { make in
make.edges.equalToSuperview()
}
}
}

核心功能

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




界面定制

注意:
界面定制、图标定制、文案定制这部分章节内容,涉及到需要修改TUIRoomKit 组件源码,通过 CocoaPods 依赖管理器集成TUIRoomKit将被视为“不可变”的依赖项。每次执行 pod install 时,CocoaPods 会:
检查 Podfile.lock 中记录的版本号。
从远程仓库重新下载对应版本的源码。
用下载的原始代码覆盖 Pods/ 目录下的现有文件。
因此,任何对 Pods/ 目录的手动修改都只是临时性的,下次执行安装命令时即被还原。
推荐解决方案:
Fork TUIRoomKit 的官方仓库。
在 fork 的仓库中修复问题并提交。
修改 Podfile,指向自定义仓库和分支。
pod 'TUIRoomKit', :git => 'https://github.com/your-username/TUIRoomKit.git', :branch => 'your-branch'
RoomMainView房间主页面内功能丰富,可定制化度高,开发者可以根据实际产品需求,对 UI 进行定制化修改,以适配业务交互场景。以下将详细为开发者展示RoomMainView页面中视图组件,便于开发者快速修改。



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

图标定制

通过 CocoaPods 方式接入 TUIRoomKit组件后,开发者可以根据实际 UI 交互需求直接替换组件下的图标资源, 以适配开发者的业务场景,
TUIRoomKit 使用 TUIRoomKit.xcassets管理 UI 所需的图片资源,您可以借助 Xcode 图形化工具快速修改自定义界面所需的图标。

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



camera_close.png
摄像头关闭图标



camera_open.png
摄像头开启图标



room_mic_off_red.png
麦克风关闭图标



room_mic_on_big.png
麦克风开启图标



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



room_owner_tag.png
房主身份标识图标

文案定制

TUIRoomKit 使用更为方便的 Apple Strings Catalog 工具来管理 UI 所需的文案显示,您可以很直观的通过 Xcode 视图化管理工具修改需要调整的文案:
说明:
Apple Strings Catalog (.xcstrings) 是在 Xcode 15 中引入的本地化格式。它增强了开发者管理本地化字符串的方式,支持处理复数、设备特定变体等的结构化格式。这种格式正成为管理 iOS 和 macOS 应用程序本地化的推荐方法。




常见问题

pod install 执行后本地安装找不到 TUIRoomKit 最新版本?

如果无法安装 TUIRoomKit 最新版本,请按以下步骤操作:
1. 在 Podfile 所在目录下删除 Podfile.lock Pods,您可以选择手动删除或终端执行以下命令:
// cd 到 Podfile 所在目录下

rm -rf Pods/
rm Podfile.lock
2. 在 Podfile 所在目录下执行 pod install --repo-update
// cd 到 Podfile 所在目录下

pod install --repo-update

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

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

Podfile 文件有没有示例配置可以参考?

您可以参考 GitHub TUIKit_iOS Example 工程 Podfile 示例文件。