即时通信 IM 接入概览（iOS）

一、核心功能

AtomicXCore 中用于搭建多人音视频房间场景所需要使用到的核心模块包含以下三个：

·RoomStore：房间管理功能入口，包含功能：预定房间、创建房间、加入房间、房间内呼叫等。

·RoomParticipantStore：房间内参与者功能入口， 包含功能：管理员设置、房主转移、移出房间、参与者设备控制等。

·RoomParticipantView：房间内参与者视频画面视图。

三、步骤1：开通服务

请参见 开通服务，获取体验版或付费版 SDK。

四、步骤2：环境要求

·Xcode：需使用 Xcode 15 或更高版本。

·iOS 系统：支持 iOS 13.0 或更高版本的设备。

·CocoaPods 环境：已安装 CocoaPods 环境。如果你尚未安装，请参见 CocoaPods 页面安装，或按以下步骤操作：

·使用 gem 安装 CocoaPods：在终端中执行 sudo gem install cocoapods 命令进行安装。

注意：提示：

注意：sudo gem install cocoapods 安装过程中可能需要输入电脑密码，按提示输入管理员密码即可。

五、步骤3：集成 AtomicXCore SDK

1. 添加 Pod 依赖：

已有 Podfile 文件没有 Podfile 文件在你项目的 Podfile 文件中添加 pod 'AtomicXCore' 依赖。例如：target 'YourProjectTarget' do # 其他已有的 Pod 依赖… # 添加 pod 'AtomicXCore' 依赖 pod 'AtomicXCore'end在终端中通过 cd 命令切换到你的 .xcodeproj 目录下，然后执行 pod init 命令创建 Podfile 文件，创建完成后，在你的 Podfile 文件中添加 pod 'AtomicXCore' 依赖。例如:# 如果你的项目目录是 /Users/yourusername/Projects/YourProject# 1. cd 到你的.xcodeproj 工程目录下cd /Users/yourusername/Projects/YourProject# 2. 执行 pod init，此命令运行完后，会在你的工程目录下生成一个 Podfile 文件。pod init# 3. 在生成的 Podfile 文件中添加 pod 'AtomicXCore' 依赖target 'YourProjectTarget' do # 添加 pod 'AtomicXCore' 依赖 pod 'AtomicXCore'end

2. 安装组件：

在终端中 cd 到 Podfile 文件所在的目录，然后执行以下命令安装组件。

pod install

3. 配置工程权限: 请在应用的 Info.plist 文件中添加相机和麦克风的使用权限说明。

<key>NSCameraUsageDescription</key><string>TUIRoomKit需要访问你的相机权限</string><key>NSMicrophoneUsageDescription</key><string>TUIRoomKit需要访问你的麦克风权限</string>

六、步骤4：实现登录逻辑

在项目中调用 LoginStore.shared.login 完成登录，这是使用 AtomicXCore 所有功能的关键前提。

注意：重要：

注意：推荐在自身的用户账户登录成功后，再调用 LoginStore.shared.login，以确保登录业务逻辑的清晰和一致。

import AtomicXCorefunc login() { 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)") } }}

登录接口参数说明：

八、步骤1：房主创建并加入房间

创建并加入房间具体流程如下，只需执行以下几步操作，即可快速搭建出多人房间。

注意：提示：

注意：房主创建并加入房间的业务代码，可以参考 GitHub 或者 CNB 仓库下的 TUIRoomKit 开源项目中 RoomMainViewController.swift，RoomMainView.swift 文件来了解完整的实现逻辑。

九、1. 创建并加入房间

实现方式：

1.1 配置房间初始化参数：初始化 CreateRoomOptions 设置房间名称，房间密码。

1.2 房间权限预设：设置房间内全场成员权限，例如全体静音，全体禁画等。

1.3 创建并加入房间：调用 RoomStore 的 createAndJoinRoom 接口执行核心操作。

示例代码：

import UIKitimport AtomicXCore// RoomMainViewController 代表房间主视图控制器class RoomMainViewController: UIViewController { // 初始化视图控制器并自动创建并加入房间逻辑 public init(roomID: String, roomType: RoomType) { super.init(nibName: nil, bundle: nil) createAndJoinRoom(roomID: roomID, roomType: roomType) } required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") } // 调用此方法完成创建并加入房间的复合操作 private func createAndJoinRoom(roomID: String, roomType: RoomType) { // 1. 配置房间初始化参数 // CreateRoomOptions 用于定义房间的基础属性及初始权限控制 var options = CreateRoomOptions() options.roomName = "我的讨论会" // 设置房间对外展示的名称 options.password = "" // 设置房间进入密码（若无需密码则留空） // 2. 房间权限预设：在创建之初即可控制全场权限（通常用于正式会议场景） options.isAllCameraDisabled = false // 全员开启/禁用摄像头的初始状态 options.isAllMessageDisabled = false // 全员开启/禁言的初始状态 options.isAllMicrophoneDisabled = false // 全员开启/静音的初始状态 options.isAllScreenShareDisabled = false // 全员禁止/允许屏幕分享的初始状态 // 3. 创建并加入房间 // 该方法是一个复合操作：若房间不存在则先创建，随后自动执行加入流程 RoomStore.shared.createAndJoinRoom(roomID: roomID, roomType: roomType, options: options) { [weak self] result in guard let self = self else { return } switch result { case .success(): print("创建并加入房间成功") case .failure(let error): print("创建并加入房间失败 [错误码: \\(error.code)]: \\(error.message)") } } }}

createAndJoinRoom 接口参数详细说明

CreateRoomOptions 结构体详细说明

十、2. 打开摄像头和麦克风

进房成功后调用 DeviceStore 单例对象的 openLocalCamera、openLocalMicrophone 接口打开本地设备。

import UIKitimport AtomicXCore// RoomMainViewController 代表房间主视图控制器class RoomMainViewController: UIViewController { private let roomID: String public init(roomID: String) { self.roomID = roomID super.init(nibName: nil, bundle: nil) openDevices() } required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") } // 调用此方法打开设备 private func openDevices() { // 1. 打开前置摄像头 DeviceStore.shared.openLocalCamera(isFront: true, completion: nil) // 2. 打开麦克风 DeviceStore.shared.openLocalMicrophone(completion: nil) }}

openLocalCamera 接口参数详细说明

十一、3. 结束房间

当房主期望结束房间时，调用 RoomStore 的 endRoom 接口即可结束当前房间。结束房间后，房间内的所有参与者都会收到房间结束事件。

import UIKitimport AtomicXCore// RoomMainViewController 代表房间主视图控制器class RoomMainViewController: UIViewController { private let roomID: String public init(roomID: String) { self.roomID = roomID super.init(nibName: nil, bundle: nil) endRoom() } required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") } /// 调用此方法结束房间 private func endRoom() { // endRoom 接口用于永久结束当前房间。 // 注意：通常该操作仅限房主（Owner）执行，执行后所有成员将被移出房间且音视频采集会强制停止。 RoomStore.shared.endRoom { [weak self] result in guard let self = self else { return } switch result { case .success(): print("结束房间成功") case .failure(let error): print("结束房间失败 [错误码: \\(error.code)]: \\(error.message)") } } }}

十二、步骤2：参与者加入房间

参与者加入房间，通过简单几步操作，即可实现与房间内其他参与者进行实时音视频互动。

十三、1. 加入房间

参与者需要加入房间时，调用 RoomStore 的 joinRoom 接口，即可加入房间，此时房间内其他参与者会收到参与者加入房间事件通知。

import UIKitimport AtomicXCore// RoomMainViewController 代表房间主视图控制器class RoomMainViewController: UIViewController { public init(roomID: String, roomType: RoomType) { super.init(nibName: nil, bundle: nil) joinRoom(roomID: roomID, roomType: roomType) } required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") } /// 调用此方法加入一个已存在的房间 private func joinRoom(roomID: String, roomType: RoomType) { // 1. 准备加入参数 // joinRoom 适用于加入一个已知且正在进行的房间 let targetRoomID = roomID // 目标房间 ID let roomPassword = "" // 房间密码，若房间未设置密码则传空字符串或 nil // 2. 调用 RoomStore 加入房间接口 // 该操作会验证房间是否存在、用户是否被禁入以及密码是否正确 RoomStore.shared.joinRoom(roomID: targetRoomID, roomType: roomType, password: roomPassword) { [weak self] result in guard let self = self else { return } switch result { case .success(): print("加入房间成功") case .failure(let error): print("加入房间失败 [错误码: \\(error.code)]: \\(error.message)") } } }}

joinRoom 接口参数详细说明

十四、2. 打开摄像头和麦克风

代码示例可参考 打开摄像头和麦克风 步骤。

十五、3. 离开房间

当参与者要离开房间时，通过调用 RoomStore 的 leaveRoom 接口即可离开房间，此时房间内其他参与者都会收到参与者离开房间事件通知。

import UIKitimport AtomicXCore// RoomMainViewController 代表房间主视图控制器class RoomMainViewController: UIViewController { private let roomID: String public init(roomID: String) { self.roomID = roomID super.init(nibName: nil, bundle: nil) leaveRoom() } required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") } /// 调用此方法主动退出当前房间 private func leaveRoom() { // 1. 业务逻辑说明 // leaveRoom 接口用于普通成员或房主主动退出房间。 // 与 endRoom 不同，房主调用 leaveRoom 只会让自己离开，房间依然存在。 // 2. 调用 RoomStore 离开房间接口 // 该操作会停止音视频流传输，并通知服务器将当前用户移出房间 RoomStore.shared.leaveRoom { [weak self] result in guard let self = self else { return } switch result { case .success(): print("退出房间成功") case .failure(let error): print("退出房间失败 [错误码: \\(error.code)]: \\(error.message)") } } }}

十六、步骤3：绑定视频画面视图

AtomicXCore SDK 的 RoomParticipantView 组件为开发者提供了完整的视频画面渲染解决方案。该组件支持本地摄像头画面和远端参与者视频流的实时显示，集成过程简单高效。

注意：提示：

注意：RoomParticipantView 是用于渲染房间参与者视频流的核心视图组件，若需要更灵活的视频组件布局方式，请参考 GitHub 或者 CNB 仓库的 TUIRoomKit 开源项目中 RoomView.swift 文件来了解完整的实现逻辑。

十七、实现方式：

1. 数据层订阅：订阅 RoomParticipantStore.state.participantList，建立参与者状态的响应式监听。

2. 状态自动同步：参与者列表变更时，系统自动更新 participantList 状态数据。

3. 视图初始化：根据参与者数据实例化 RoomParticipantView，绑定视频渲染逻辑。

4. UI 集成：完成视图层级集成、布局配置和渲染激活。

十八、示例代码：

import UIKitimport Combineimport AtomicXCore// RoomMainViewController 代表房间主视图控制器class RoomMainViewController: UIViewController { private var participantStore: RoomParticipantStore private var cancellableSet = Set<AnyCancellable>() private var views = [RoomParticipantView]() init(roomID: String) { // RoomParticipantStore 是与房间绑定的，需要通过 RoomParticipantStore.create(roomID: String) 工厂方法来为特定的房间创建实例 participantStore = RoomParticipantStore.create(roomID: roomID) super.init(nibName: nil, bundle: nil) // 1. 数据层订阅 subscribeParticipantState() participantStore.getParticipantList(cursor: "", completion: nil) } required init?(coder: NSCoder) { fatalError() } private func subscribeParticipantState() { participantStore.state.subscribe(StatePublisherSelector(keyPath: \\.participantList)) .receive(on: DispatchQueue.main) .sink { [weak self] participantList in guard let self = self else { return } // 2. 状态自动同步 updateParticipantView(participantList) } .store(in: &cancellableSet) } private func updateParticipantView(_ list: [RoomParticipant]) { views.forEach { view in view.setActive(isActive: false) view.removeFromSuperview() } views = Array(list.prefix(9)).enumerated().map { index, participant in // 3. 视图初始化 let participantView = RoomParticipantView(streamType: .camera, participant: participant) participantView.frame = CGRect(x: CGFloat(index % 3) * 125 + 10, y: CGFloat(index / 3) * 165 + 100, width: 120, height: 160) // 4. UI 集成 view.addSubview(participantView) participantView.setActive(isActive: true) return participantView } }}

RoomParticipantView 构造接口参数详细说明：

RoomParticipant 结构体参数详细说明：

十九、步骤4：监听房间内事件

进入房间完成后，通过调用 RoomStore 的 roomEventPublisher 可以订阅到 RoomEvent 中与房间相关的被动事件。

import UIKitimport Combineimport AtomicXCore// RoomMainViewController 代表房间主视图控制器class RoomMainViewController: UIViewController { private let roomID: String // 用于存储 Combine 订阅关系，防止对象销毁导致监听失效 private var cancellableSet = Set<AnyCancellable>() public init(roomID: String) { self.roomID = roomID super.init(nibName: nil, bundle: nil) // 核心流程：在初始化时开启事件监听 subscribeRoomEvents() } required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") } /// 调用此方法订阅房间被动事件 private func subscribeRoomEvents() { // 1. 访问 RoomStore 的 roomEventPublisher // 该 Publisher 会推送房间全生命周期的事件，例如呼叫、解散、预约提醒等 RoomStore.shared.roomEventPublisher .receive(on: RunLoop.main) // 确保在主线程处理 UI 逻辑 .sink { [weak self] event in guard let self = self else { return } // 2. 根据事件类型执行相应的业务逻辑 switch event { case .onRoomEnded(let roomInfo): print("当前所在房间已结束") // … 处理其他 RoomEvent 事件 … default: break } } .store(in: &cancellableSet) // 3. 存储订阅关系 }}

20、运行效果

通过完成以上搭建步骤，你将得到一个纯净的多人视频渲染房间，但没有任何 UI 交互。

21、丰富多人房间功能

为了满足对多人房间更多的需求，AtomicXCore SDK 还提供了以下功能来丰富多人房间场景。

22、API 文档

24、RoomParticipantView 绑定了其他参与者信息，并正确设置了视频流类型，依然看不到视频画面？

·检查 setActive：请确保当前 RoomParticipantView 在屏幕中是可见状态，并正确调用 RoomParticipantView 的 setActive：true。

·检查 RoomParticipant: 请确保 RoomParticipantView 中设置的 RoomParticipant 的 cameraStatus 状态是否为 on。

·检查网络：请检查设备网络连接是否正常。

25、rsync 因权限不足导致依赖第三方库资源拷贝失败

例如在使用 Xcode 集成 SnapKit 框架进行开发时，可能会遇到如下编译报错：

rsync(xxxx):1:1: SnapKit.framework/SnapKit_Privacy.bundle/: mkpathat: Operation not permitted

26、问题原因

Xcode 的用户脚本沙盒机制限制了构建过程中 rsync 脚本对 SnapKit.framework 资源文件的写入权限，导致框架内的 SnapKit_Privacy.bundle 无法正常拷贝。

27、解决步骤

1. 关闭用户脚本沙盒后，打开 Xcode 项目，进入项目的 Build Settings，搜索 User Script Sandboxing（或标识 ENABLE_USER_SCRIPT_SANDBOXING），将其值从 YES 修改为 NO。

2. 清理并重新构建项目执行 Product → Clean Build Folder 清理项目缓存，然后重新编译运行即可。

28、联系我们

如果在接入或使用过程中有任何疑问或者建议，欢迎 联系我们 提交反馈。