TUIRoomKit 是腾讯云提供的一站式多人音视频房间解决方案,集成了完整的 UI 组件和核心功能。通过本文档,开发者可以选择 Swift Package Manager 或 External Pods(CocoaPods)两种方式将 TUIRoomKit 集成到项目中,实现多人音视频房间功能。本文还将详细介绍如何快速替换图片资源、本地化文案等个性化配置,帮助开发者打造符合品牌特色的音视频应用。
房间准备页 | 房间主页 | 成员管理 |
![]() | ![]() | ![]() |
前提条件
开通服务
SDKAppID:应用标识(必填),腾讯云基于 SDKAppID 完成计费统计。
SDKSecretKey:应用密钥,用于初始化配置文件的密钥信息。
环境准备
SwiftPM 方式需 Xcode 16+ / iOS 14.0+;
CocoaPods 方式需 Xcode 15+ / iOS 14.0+;
使用 CocoaPods 方式时请确认已安装 CocoaPods。
快速接入
步骤1:导入 SDK
1. 以 Xcode 为例,进入
File > Add Package Dependencies...,在搜索中粘贴如下 URL,等待结果出来后点击 Add Package。https://github.com/Tencent-RTC/RoomKit_SwiftPM.git
2. 在
Choose Package Options 中选择要使用的已发布版本。可参考 Apple 官方文档 设置版本规则。3. 将
TUIRoomKit 添加到 App Target。使用本文示例时,还需在 Target 的 Frameworks, Libraries, and Embedded Content 中添加已解析依赖的 AtomicXCore 和 SnapKit product,无需重复添加仓库。注意:
1. 在终端窗口执行以下命令安装 CocoaPods,如果您已经完成 CocoaPods 的安装,可以跳过该步。
sudo gem install cocoapods
2. 在项目根目录执行
pod init 创建 Podfile 文件,并编辑保存内容如下。platform :ios, '14.0'# 将 App 修改为您项目的名称target 'App' dopod 'AtomicXCore', :podspec => 'https://sdk-liteav-1252463788.cos.ap-hongkong.myqcloud.com/app/tuikit/download/latest/AtomicXCore.podspec'# 官方维护的默认版本地址pod 'TUIRoomKit', :podspec => 'https://sdk-liteav-1252463788.cos.ap-hongkong.myqcloud.com/app/tuikit/download/latest/TUIRoomKit.podspec'end
3. 在终端窗口中执行以下命令,完成 SDK 的下载。
pod install
注意:
请同时添加
AtomicXCore 的 external podspec,其他依赖由 CocoaPods 自动解析。安装后打开 .xcworkspace 工程。两个默认版本地址独立更新,生产环境建议使用配套的版本化地址,写法见 常见问题。步骤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 组件中,MeetingView 是集成了完整的多人音视频房间功能的核心界面,以下将向开发者演示如何以房主身份将 MeetingView 嵌入到应用中。实现方式
1. 遵守路由导航协议:
TUIRoomKit 内部使用 RouterContext 协议管理页面间的路由跳转。宿主视图控制器需要声明遵循该协议,以确保组件内部的导航操作(例如结束房间、返回上一页)能够正确执行。2. 懒加载创建视图页面:在控制器内部以懒加载方式实例化
MeetingView,并为其设置 routerContext 属性。该属性使得视图能够通过协议方法调用宿主控制器的导航功能。3. 构造进房的配置项:进入房间后是否需要自动打开音视频设备的配置项。
4. 初始化房间主页面:通过房主身份初始化房间主页面。
5. 将视图添加到控制器:在控制器的
viewDidLoad 方法中,将 MeetingView 加入视图层级,并使用约束布局使其充满整个控制器视图区域。说明:
TUIRoomKit 的内部页面跳转机制基于 UINavigationController 的标准导航方法(push/pop)实现。为确保页面路由功能正常工作,开发者的视图控制器必须作为 UINavigationController 的根视图控制器或位于其导航栈内。若未将控制器包装至 UINavigationController 中,SDK 内部的跳转操作将因缺少有效的导航上下文而失效,导致页面无法正常切换。示例代码
import UIKitimport TUIRoomKitimport SnapKitimport AtomicXCore// YourMainViewController 代表您加载房间主页面的视图控制器// 1. YourMainViewController 需要遵守 TUIRoomKit 组件中的 RouterContext 协议class YourMainViewController: UIViewController, RouterContext {// 2. 懒加载创建 TUIRoomKit 中的 MeetingView 房间主页面private lazy var meetingView: MeetingView = {// 3. 构造进房的配置项let config = RoomConnectConfig(autoEnableMicrophone: true, // 进房后是否自动开启麦克风autoEnableCamera: true, // 进房后是否自动开启摄像头autoEnableSpeaker: true) // 进房后是否自动开启扬声器// 4. 房间名称var options = CreateRoomOptions()options.roomName = "xxx"let view = MeetingView(roomID: "roomID", behavior: .createAndJoinRoom(options: options), config: config)view.routerContext = selfreturn view}()public override func viewDidLoad() {super.viewDidLoad()// 5. 将 MeetingView 对象 添加到视图控制器中view.addSubview(meetingView)meetingView.snp.makeConstraints { make inmake.edges.equalToSuperview()}}}
MeetingView
构造函数参数详细说明:
参数 | 类型 | 说明 |
roomID | String | 字符串类型的房间唯一标识符。 限制长度为 0-48 字节。 建议仅包含数字、英文字母(区分大小写)、下划线(_)和连字符(-)。避免使用空格和中文字符。 |
behavior | RoomBehavior | 房间主页面初始化来源。 createAndJoinRoom:房主身份创建并加入房间。此方式需要构造创建房间配置项,关于 CreateRoomOptions 的详细用法请参考:CreateRoomOptions 结构体详细说明。join:参与者身份加入房间。 |
config | ConnectConfig | 进房后音视频设备控制的配置项。 |
RoomConnectConfig 参数详细说明
:参数 | 类型 | 说明 |
autoEnableMicrophone | Bool | 进房后是否自动开启麦克风。 true:自动开启 (默认值)。 false:不自动开启。 |
autoEnableCamera | Bool | 进房后是否自动开启摄像头。 true:自动开启 (默认值)。 false:不自动开启。 |
autoEnableSpeaker | Bool | 进房后是否自动开启扬声器。 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:加入房间
以下示例将向开发者演示如何以参与者身份将
MeetingView 嵌入到应用中。实现方式:
1. 遵守路由导航协议:
TUIRoomKit 内部使用 RouterContext 协议管理页面间的路由跳转。宿主视图控制器需要声明遵循该协议,以确保组件内部的导航操作(例如结束房间、返回上一页)能够正确执行。2. 懒加载创建视图页面:在控制器内部以懒加载方式实例化
MeetingView,并为其设置 routerContext 属性。该属性使得视图能够通过协议方法调用宿主控制器的导航功能。3. 构造进房的配置项:进入房间后是否需要自动打开音视频设备的配置项。
4. 初始化房间主页面:通过参与者身份初始化房间主页面。
5. 将视图添加到控制器:在控制器的
viewDidLoad 方法中,将 MeetingView 加入视图层级,并使用约束布局使其充满整个控制器视图区域。代码示例
import UIKitimport TUIRoomKitimport SnapKitimport AtomicXCore// YourMainViewController 代表您加载房间主页面的视图控制器// 1. YourMainViewController 需要遵守 TUIRoomKit 组件中的 RouterContext 协议class YourMainViewController: UIViewController, RouterContext {// 2. 懒加载创建 TUIRoomKit 中的 MeetingView 房间主页面private lazy var meetingView: MeetingView = {// 3. 构造进房的配置项let config = RoomConnectConfig(autoEnableMicrophone: true, // 进房后是否自动开启麦克风autoEnableCamera: true, // 进房后是否自动开启摄像头autoEnableSpeaker: true) // 进房后是否自动开启扬声器// 4. 参与者身份初始化房间主页面let view = MeetingView(roomID: "roomID", behavior: .join, config: config)view.routerContext = selfreturn view}()public override func viewDidLoad() {super.viewDidLoad()// 5. 将 MeetingView 对象 添加到视图控制器中view.addSubview(meetingView)meetingView.snp.makeConstraints { make inmake.edges.equalToSuperview()}}}
AI 助手:知识咨询与代码集成
您在接入视频会议 SDK 过程中,可以通过 MCP 使用 AI 助手,快速完成知识咨询、报错排查和集成代码生成。支持 Web/Android/iOS/Flutter/uni-app/HarmonyOS 等平台,答案基于官方文档。适用于查询 Room 组件和 AtomicXCore SDK 用法以及集成文档等场景,立即体验,提出您的第一个问题。
核心功能
接入
MeetingView 代码后,开发者将得到一个完整的多人音视频页面,内部包含成员管理,音视频设备控制,房间信息展示等功能,这是 TUIRoomKit 组件的核心。

界面定制
注意:
不要直接修改依赖缓存,重新下载可能覆盖改动。SwiftPM 定制请克隆或 Fork RoomKit_SwiftPM,改用本地包;CocoaPods 定制请使用包含
TUIRoomKit.podspec 的组件源码目录,通过 :path 引入。SwiftPM 壳仓库不能直接用作 CocoaPods 本地依赖。MeetingView 房间主页面内功能丰富,可定制化度高,开发者可以根据实际产品需求,对 UI 进行定制化修改,以适配业务交互场景。以下将详细为开发者展示 MeetingView 页面中视图组件,便于开发者快速修改。

MeetingView 中的组件详细说明注意:
下表链接指向组件源码仓库中的源文件,便于查看实现;SwiftPM 包内源码统一位于
Sources/ 目录下。组件 | 功能描述 | 定制化建议 |
房间主视图容器,负责协调各子组件的布局与数据流转。 | 可调整整体背景、安全区域适配、组件显隐逻辑。 | |
顶部导航栏,包含房间信息、网络状态、摄像头和声音控制、退出房间功能入口。 | 可替换图标、调整背景透明度、添加自定义按钮(例如录制、 窗口化)。 | |
视频流展示区域,采用瀑布流布局管理多个用户视频画面。 | 可修改布局算法(行列数、间距)、分页指示器样式、空状态视图。 | |
单个视频流单元格挂件,承载用户视频画面与基本信息。 | 可定制用户信息面板(头像、徽章)、互动控件(语音波形)。 | |
底部工具栏,集成麦克风、摄像头、扬声器麦克风切换,成员管理、屏幕分享、云端录制、设置等操作按钮。 | 可重新排列按钮顺序、修改按钮样式(颜色、尺寸)、添加业务相关功能(例如屏幕分享、会中呼叫、美颜)。 |
图标定制
接入
TUIRoomKit 组件后,开发者可以根据实际 UI 交互需求直接替换组件下的图标资源, 以适配开发者的业务场景。TUIRoomKit 使用 TUIRoomKitIcons.xcassets 管理 UI 所需的图片资源,您可以借助 Xcode 图形化工具快速修改自定义界面所需的图标。

常用的图片文件列表
图标 | 文件名 | 说明 |
| roomkit_icon_camera_off.svg | 摄像头关闭图标 |
| roomkit_icon_camera.svg | 摄像头开启图标 |
| roomkit_icon_microphone_off.svg | 麦克风关闭图标 |
| roomkit_icon_microphone.svg | 麦克风开启图标 |
| roomkit_icon_screen_share.svg | 屏幕分享图标 |
文案定制
说明:
Apple Strings Catalog (.xcstrings) 是在 Xcode 15 中引入的本地化格式。它增强了开发者管理本地化字符串的方式,支持处理复数、设备特定变体等的结构化格式。这种格式正成为管理 iOS 和 macOS 应用程序本地化的推荐方法。


常见问题
如何指定版本?
SwiftPM:在 Xcode 的 Package Dependencies 中选择已发布版本,使用
Exact Version 锁定版本。External Pods:将两行默认地址换成配套的版本化 podspec 地址。下列
ROOM_VERSION、CORE_VERSION 分别为组件版本,ROOM_MAJOR_MINOR、CORE_MAJOR_MINOR 为各自版本号的前两段;请替换后使用,不要假定两个组件的版本号相同。pod 'AtomicXCore', :podspec => 'https://sdk-liteav-1252463788.cos.ap-hongkong.myqcloud.com/app/tuikit/download/release/CORE_MAJOR_MINOR/AtomicXCore_CORE_VERSION.podspec'pod 'TUIRoomKit', :podspec => 'https://sdk-liteav-1252463788.cos.ap-hongkong.myqcloud.com/app/tuikit/download/release/ROOM_MAJOR_MINOR/TUIRoomKit_ROOM_VERSION.podspec'
如何升级 External Pods?
打开两行默认地址,查看各自的
s.version 即可查询默认版本。升级时先确认两个组件兼容;指定版本时,先更新为配套的 podspec 地址,再执行:pod update TUIRoomKit AtomicXCore
pod install 通常保留 Podfile.lock 中的版本,不会主动升级。请提交更新后的 Podfile.lock,不要为升级 SDK 删除整个锁文件。集成或编译失败怎么办?
SwiftPM 解析失败:检查网络,在
File > Packages 中执行 Resolve Package Versions;仍失败时尝试 Reset Package Caches。requires Swift tools version 6.0:使用 Xcode 16 或更高版本。No such module:SwiftPM 检查 App Target 是否添加了 TUIRoomKit、AtomicXCore、SnapKit;CocoaPods 确认两行 podspec 均已添加,并通过 .xcworkspace 打开工程。AtomicXCore 缺少 API:检查所选版本是否与 TUIRoomKit 兼容,必要时改用配套的版本化地址。每次进房都需要调用登录吗?
不需要。通常只需调用一次
LoginStore.shared.login,建议将 login / logout 与自己的登录业务关联。SwiftPM 工程如何修改 Package.swift?
以下是配置片段,不是完整清单。将
ROOM_VERSION 替换为已发布版本,在现有包的 dependencies 中添加:.package(url: "https://github.com/Tencent-RTC/RoomKit_SwiftPM.git", from: "ROOM_VERSION")
在使用组件的 target 的
dependencies 中添加:.product(name: "TUIRoomKit", package: "RoomKit_SwiftPM")
package: 使用包身份 RoomKit_SwiftPM,不是模块名 TUIRoomKit。业务代码直接导入 AtomicXCore 或 SnapKit 时,还需在现有包清单中声明对应仓库依赖,并将其同名 product 添加到 target;版本要求参考所选 RoomKit_SwiftPM tag 下的 Package.swift。

