帮你快速理解、总结文档立即下载

iOS

最近更新时间:2026-11-17 09:30:07
本文档已由 AI 辅助审校
我的收藏
TUIRoomKit 是腾讯云提供的一站式多人音视频房间解决方案,集成了完整的 UI 组件和核心功能。通过本文档,开发者可以选择 Swift Package Manager 或 External Pods(CocoaPods)两种方式将 TUIRoomKit 集成到项目中,实现多人音视频房间功能。本文还将详细介绍如何快速替换图片资源、本地化文案等个性化配置,帮助开发者打造符合品牌特色的音视频应用。
房间准备页
房间主页
成员管理











前提条件

开通服务

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

环境准备

SwiftPM 方式需 Xcode 16+ / iOS 14.0+;
CocoaPods 方式需 Xcode 15+ / iOS 14.0+;
使用 CocoaPods 方式时请确认已安装 CocoaPods。

快速接入

步骤1:导入 SDK

Swift Package Manager 集成
CocoaPods 集成
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,无需重复添加仓库。
注意:
SwiftPM 方式需 Xcode 16 或更高版本;其他环境要求见 环境准备。
1. 在终端窗口执行以下命令安装 CocoaPods,如果您已经完成 CocoaPods 的安装,可以跳过该步。
sudo gem install cocoapods
2. 在项目根目录执行 pod init 创建 Podfile 文件,并编辑保存内容如下。
platform :ios, '14.0'

# 将 App 修改为您项目的名称
target 'App' do
pod '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 工程。两个默认版本地址独立更新,生产环境建议使用配套的版本化地址,写法见 常见问题。
两种方式请二选一,避免重复引入 SDK。SwiftPM 可用版本见 RoomKit_SwiftPM Tags;本文示例的 API 以所选版本为准。

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

步骤4:设置头像和昵称

首次登录的用户没有头像和昵称信息,需要通过 LoginStore 的 setSelfInfo 接口设置个人信息:
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 组件中,MeetingView 是集成了完整的多人音视频房间功能的核心界面,以下将向开发者演示如何以房主身份将 MeetingView 嵌入到应用中。

实现方式

1. 遵守路由导航协议:TUIRoomKit 内部使用 RouterContext 协议管理页面间的路由跳转。宿主视图控制器需要声明遵循该协议,以确保组件内部的导航操作(例如结束房间、返回上一页)能够正确执行。
2. 懒加载创建视图页面:在控制器内部以懒加载方式实例化 MeetingView,并为其设置 routerContext 属性。该属性使得视图能够通过协议方法调用宿主控制器的导航功能。
3. 构造进房的配置项:进入房间后是否需要自动打开音视频设备的配置项。
4. 初始化房间主页面:通过房主身份初始化房间主页面。
5. 将视图添加到控制器:在控制器的 viewDidLoad 方法中,将 MeetingView 加入视图层级,并使用约束布局使其充满整个控制器视图区域。
说明:
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 中的 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 = self
return view
}()
public override func viewDidLoad() {
super.viewDidLoad()
// 5. 将 MeetingView 对象 添加到视图控制器中
view.addSubview(meetingView)
meetingView.snp.makeConstraints { make in
make.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 UIKit
import TUIRoomKit
import SnapKit
import 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 = self
return view
}()
public override func viewDidLoad() {
super.viewDidLoad()
// 5. 将 MeetingView 对象 添加到视图控制器中
view.addSubview(meetingView)
meetingView.snp.makeConstraints { make in
make.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/ 目录下。
组件
功能描述
定制化建议
房间主视图容器,负责协调各子组件的布局与数据流转。
可调整整体背景、安全区域适配、组件显隐逻辑。
顶部导航栏,包含房间信息、网络状态、摄像头和声音控制、退出房间功能入口。
可替换图标、调整背景透明度、添加自定义按钮(例如录制、 窗口化)。
RoomView
视频流展示区域,采用瀑布流布局管理多个用户视频画面。
可修改布局算法(行列数、间距)、分页指示器样式、空状态视图。
单个视频流单元格挂件,承载用户视频画面与基本信息。
可定制用户信息面板(头像、徽章)、互动控件(语音波形)。
底部工具栏,集成麦克风、摄像头、扬声器麦克风切换,成员管理、屏幕分享、云端录制、设置等操作按钮。
可重新排列按钮顺序、修改按钮样式(颜色、尺寸)、添加业务相关功能(例如屏幕分享、会中呼叫、美颜)。

图标定制

接入 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
屏幕分享图标

文案定制

TUIRoomKit 使用更为方便的 Apple Strings Catalog 工具来管理 UI 所需的文案显示,您可以很直观的通过 Xcode 视图化管理工具修改需要调整的文案:
说明:
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。