本文档介绍如何在应用中集成 TUIRoomKit 研讨会场景。该场景支持主持人、嘉宾与万级以上观众的实时互动,具备超低延时观看和高性能的消息处理能力。
标准会议与研讨会有何不同?
标准会议(Conference):适用于中小规模的多人协作场景,所有参与者均具有平等的音视频权限,提供屏幕共享、成员管理等完整互动能力。
研讨会(Webinar):专为大型直播演讲设计,支持无上限观众进房观看。观众可举手申请上台成为嘉宾后参与讨论,且系统针对万人级互动场景优化了消息并发性能,满足更专业的演讲互动需求。
功能展示
主持人 | 嘉宾 | 观众 |
支持主持人发起高清音视频推流与屏幕共享,支持对成员进行管理。 | 支持嘉宾开启麦克风进行实时语音讨论和分享。 | 支持观众无上限并发进房,以超低延迟观看实况并参与高频消息互动。支持观众通过“举手”功能向主持人申请变更为嘉宾。 |
![]() | ![]() | ![]() |
前提条件
开通服务
SDKAppID: 应用标识,腾讯云基于
SDKAppID 完成计费统计。SDKSecretKey: 应用密钥,用于初始化配置文件的密钥信息。
注意:
研讨会场景基于底层的直播能力构建。请注意接入研讨会能力需要领取 TUILiveKit 体验版或开通 TUILiveKit 正式版,以确保相关功能的正常运行。
环境准备
在开始运行 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 {let roomID = "webinar_123456"// 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 = "xxx的网络研讨会" // 房间名称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 init 函数参数详细说明
:参数 | 类型 | 说明 |
roomID | String | 字符串类型的房间唯一标识符。 限制长度为 0-48 字节。 建议仅包含数字、英文字母(区分大小写)、下划线(_)和连字符(-)。避免使用空格和中文字符。 |
roomType | RoomType | 房间类型 standard:标准房间。webinar:大型研讨会房间。研讨会场景这里填写 webinar 房间类型 |
behavior | RoomBehavior | 房间主页面初始化来源。 Create: 房主身份创建房间。此方式需要构造创建房间配置项,关于 CreateRoomOptions 的详细用法请参考:CreateRoomOptions 结构体详细说明。 Join:成员身份加入房间。 |
config | ConnectConfig | 进房后音视频设备控制的配置项。 |
ConnectConfig 参数详细说明
:参数 | 类型 | 说明 |
autoEnableMicrophone | Bool | 进房后是否自动开启麦克风 true:自动开启 (默认值)。 false:不自动开启。 |
autoEnableCamera | Bool | 进房后是否自动开启摄像头。 true:自动开启 (默认值)。 false:不自动开启。 |
autoEnableSpeaker | Bool | 进房后是否自动开启扬声器。 true:自动开启 (默认值)。 false:不自动开启。 |
CreateRoomOptions 结构体详细说明
参数名 | 类型 | 必填 | 说明 |
roomName | String | 否 | 房间名称,可以不设置,默认为空字符串。 限制长度为 0-60 字节。 支持中英文、数字、特殊字符。 |
password | String | 否 | 房间密码,空字符串 "" 通常表示该房间不设密码。 限制长度为 0-32 字节。 推荐使用 4-8 位纯数字,方便移动端输入。设置后,其他用户加入房间时需输入密码。建议不要存储明文敏感信息。 研讨会场景暂时不支持密码功能,这里可以填空。 |
isAllMicrophoneDisabled | Bool | 否 | 是否全员禁止打开麦克风。开启后,除房主/管理员外,嘉宾默认禁止打开麦克风。 true:禁止。 false:取消禁止 (默认值)。 |
isAllCameraDisabled | Bool | 否 | 是否全员禁止打开摄像头。开启后,除房主/管理员外,嘉宾默认禁止打开摄像头。 true:禁止。 false:取消禁止(默认值)。 |
isAllScreenShareDisabled | Bool | 否 | 是否全员禁止发起屏幕共享。开启后,仅房主/管理员可进行屏幕共享。 true:禁止。 false:取消禁止(默认值)。 |
isAllMessageDisabled | Bool | 否 | 是否全员禁止发送聊天消息(禁言)。开启后,普通成员无法在房间内发送文字消息。 true:禁止。 false:取消禁止(默认值)。 |
步骤6:加入房间
以下示例将向开发者演示如何以参与者身份将
RoomMainView 嵌入到应用中。实现方式:
1. 遵守路由导航协议:
TUIRoomKit 内部使用 RouterContext 协议管理页面间的路由跳转。宿主视图控制器需要声明遵循该协议,以确保组件内部的导航操作(例如结束房间、返回上一页)能够正确执行。2. 懒加载创建视图页面:在控制器内部以懒加载方式实例化
RoomMainView,并为其设置 routerContext 属性。该属性使得视图能够通过协议方法调用宿主控制器的导航功能。3. 构造进房的配置项:进入房间后是否需要自动打开音视频设备的配置项。
4. 初始化房间主页面:通过参与者身份初始化房间主页面。
5. 将视图添加到控制器:在控制器的
viewDidLoad 方法中,将 RoomMainView 加入视图层级,并使用约束布局使其充满整个控制器视图区域。说明:
使用 TUIRoomKit 组件进入大型研讨会房间时,需确保创建的研讨会房间的房间 ID 以
webinar_ 开头。代码示例:
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: "webinar_123456", 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 中组件详细说明组件 | 功能描述 | 定制化建议 |
房间主视图容器,负责协调各子组件的布局与数据流转。 | 可调整整体背景、安全区域适配、组件显隐逻辑。 | |
顶部导航栏,包含房间信息、摄像头和声音控制、退出房间功能入口。 | 可替换图标、调整背景透明度、添加自定义按钮(例如录制、 窗口化)。 | |
视频流展示区域,组件已封装了研讨会的流媒体处理逻辑,会根据当前用户的身份自动播放推流嘉宾的实时音视频流。 | 可修改布局位置、大小、空状态视图,视频流挂件等。 | |
底部工具栏,集成麦克风、摄像头、屏幕分享、举手列表、成员管理操作按钮。 | 可重新排列按钮顺序、修改按钮样式(颜色、尺寸)、添加业务相关功能(例如会中呼叫、美颜)。 |
图标定制
接入
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 与自己的登录业务关联。







