TUIRoomKit 是腾讯云提供的一站式多人音视频房间解决方案,集成了完整的 UI 组件和核心功能。通过本文档,开发者可以快速了解如何将 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. 安装组件:
在终端中
cd 到 Podfile 文件所在的目录,然后执行以下命令安装组件。pod install
步骤2:工程配置
为了使用音视频功能,您的应用需要获取麦克风和摄像头的权限。请在应用的
Info.plist 文件中添加以下两项,并填写对应的使用说明,这些说明将在系统请求权限时向用户显示:<key>NSCameraUsageDescription</key><string>TUIRoomKit需要访问您的相机权限</string><key>NSMicrophoneUsageDescription</key><string>TUIRoomKit需要访问您的麦克风权限</string>


步骤3:登录
代码集成完成后,需要完成登录操作,这是使用 TUIRoomKit 的关键步骤。只有在登录成功后,才能正常使用 TUIRoomKit 的各项功能,因此请仔细检查相关参数配置是否正确:
说明:
在示例代码中,登录操作是在
didFinishLaunchingWithOptions 方法内完成的。但在实际项目场景下,强烈推荐在完成自己的用户身份验证等相关登录操作后,再调用 AtomicXCore 的登录服务。这样可以避免因过早调用登录服务,导致业务逻辑混乱或数据不一致的问题,同时也能更好地适配您项目中现有的用户管理和权限控制体系。import AtomicXCore// AppDelegate.swiftfunc application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {LoginStore.shared.login(sdkAppID: 1400000001, // 替换为项目的 sdkAppIDuserID: "test_001", // 替换为项目的 userIDuserSig: "xxxxxxxxxxx") { result in // 替换为项目的 userSigswitch 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 | |
userID | String | 当前用户的唯一 ID,仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突,请勿使用 1、123 等简单 ID。 |
userSig | String | 【注意事项】 开发环境:可以采用本地 GenerateTestUserSig.genTestSig 函数生成 userSig 或者通过 UserSig 辅助工具 生成临时的 userSig。生产环境:为了防止密钥泄露,请务必采用服务端生成 userSig 的方式。详细信息请参考 服务端生成 UserSig。 |
步骤4:设置头像和昵称
首次登录的用户没有头像和昵称信息,需要通过
LoginStore 的 setSelfInfo接口设置个人信息:import AtomicXCorefunc setSelfInfo() {let userProfile = UserProfile(userID: "test_001", // 您已经登录的userIDnickname: "tom", // 设置昵称avatarURL: "http://xxx.png") // 设置头像URLLoginStore.shared.setSelfInfo(userProfile: userProfile) { result inswitch 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 UIKitimport TUIRoomKitimport SnapKitimport 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 = selfreturn view}()public override func viewDidLoad() {super.viewDidLoad()// 5. 将 RoomMainView 对象 添加到视图控制器中view.addSubview(mainView)mainView.snp.makeConstraints { make inmake.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 UIKitimport TUIRoomKitimport SnapKitimport 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 = selfreturn view}()public override func viewDidLoad() {super.viewDidLoad()// 5. 将 RoomMainView 对象 添加到视图控制器中view.addSubview(mainView)mainView.snp.makeConstraints { make inmake.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中组件详细说明组件 | 功能描述 | 定制化建议 |
房间主视图容器,负责协调各子组件的布局与数据流转。 | 可调整整体背景、安全区域适配、组件显隐逻辑。 | |
顶部导航栏,包含房间信息、摄像头和声音控制、退出房间功能入口。 | 可替换图标、调整背景透明度、添加自定义按钮(例如录制、 窗口化)。 | |
视频流展示区域,采用瀑布流布局管理多个用户视频画面。 | 可修改布局算法(行列数、间距)、分页指示器样式、空状态视图。 | |
单个视频流单元格,承载用户视频画面与基本信息。 | 可自定义视频渲染层、用户信息面板(头像、徽章)、互动控件(语音波形)。 | |
底部工具栏,集成麦克风、摄像头、成员管理操作按钮。 | 可重新排列按钮顺序、修改按钮样式(颜色、尺寸)、添加业务相关功能(例如屏幕分享、会中呼叫、美颜)。 |
图标定制
通过 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 | 房主身份标识图标 |
文案定制
说明:
Apple Strings Catalog (.xcstrings) 是在 Xcode 15 中引入的本地化格式。它增强了开发者管理本地化字符串的方式,支持处理复数、设备特定变体等的结构化格式。这种格式正成为管理 iOS 和 macOS 应用程序本地化的推荐方法。


常见问题
pod install 执行后本地安装找不到 TUIRoomKit 最新版本?
如果无法安装
TUIRoomKit 最新版本,请按以下步骤操作:1. 在 Podfile 所在目录下删除
Podfile.lock 和 Pods,您可以选择手动删除或终端执行以下命令:// cd 到 Podfile 所在目录下rm -rf Pods/rmPodfile.lock
2. 在 Podfile 所在目录下执行
pod install --repo-update:// cd 到 Podfile 所在目录下pod install --repo-update
每次进房都需要调用登录吗?
不需要。通常您只需要完成一次
LoginStore.shared.login 调用即可,我们建议您将 LoginStore.shared.login 和 LoginStore.shared.logout 与自己的登录业务关联。







