# 实现语聊房 (/zh-CN/solutions/chatroom/uikit/build/quick-integration/ios) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文介绍如何集成语聊 UIKit 来实现语聊房间的创建和销毁、用户进房和退房等功能。 ## 示例项目 [#示例项目-1] `API-Examples-AUIKit` 是极简语聊项目。你可以参考该项目了解本文提供的集成步骤和代码逻辑。 ## 准备开发环境 [#准备开发环境-1] ### 前提条件 [#前提条件-1] - [Xcode](https://apps.apple.com/cn/app/xcode/id497799835?mt=12) 14.0 及以上。 - iOS 设备,版本 13.0 及以上。 - 有效的苹果开发者账号。 - 可以访问互联网的计算机。确保你的网络环境没有部署防火墙,否则无法正常使用声网服务。 - [开通语聊房 UIKit 相关服务](/zh-CN/solutions/chatroom/uikit/build/enable-service)。 ### 创建项目 [#创建项目-1] 本节介绍如何在 Xcode 创建项目: 1. [创建一个新的项目](https://help.apple.com/xcode/mac/current/#/dev07db0e578),**Application** 选择 **App**,**Interface** 选择 **Storyboard**,**Language** 选择 **Swift**。 :::warning[注意] 如果你没有添加过开发团队信息,会看到 **Add account…** 按钮。点击该按钮并按照屏幕提示登入 Apple ID,点击 **Next**,完成后即可选择你的 Apple 账户作为开发团队。 ::: 2. 为你的项目设置[自动签名](https://help.apple.com/xcode/mac/current/#/dev23aab79b4)。本文假设项目名为 `AUIKitDemo`。 3. 设置部署你的 App 的[目标设备](https://help.apple.com/xcode/mac/current/#/deve69552ee5)。 4. 设置 **Minimum Deployments** 为 iOS 13.0。 ![Xcode Minimum Deployments 设置示意图](https://web-cdn.agora.io/docs-files/1697686309702) 5. 添加项目的设备权限。在项目导航栏中打开 `info.plist` 文件,编辑[属性列表](https://help.apple.com/xcode/mac/current/#/dev3f399a2a6),添加以下属性: | key | type | value | | -------------------------------------- | ------ | ------------------------------------------------------------ | | Privacy - Microphone Usage Description | String | 使用麦克风的目的,例如 for a live interactive streaming | ### 集成依赖 [#集成依赖-1] 本节介绍如何集成语聊项目所需的依赖库: 1. 开始前请确保你已安装 CocoaPods,如尚未安装 CocoaPods,参考 [Getting Started with CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started) 安装说明。 2. 下载声网提供的 [AUIVoiceRoom](https://github.com/AgoraIO-Community/AUIVoiceRoom) 仓库: ```shell git clone git@github.com:AgoraIO-Community/AUIVoiceRoom.git ``` 3. 将 `AUIVoiceRoom/iOS/AScenesKit/AScenesKit` 文件夹复制到与你的 `*.xcodeproj` 文件同层级的位置。 4. 将 `AUIVoiceRoom/iOS/AUIVoiceRoom/AUIVoiceRoom/VoiceChatUIKit.swift` 文件复制到与 `*.xcodeproj` 文件同层级的 Demo 文件夹里。具体步骤如下: 1. 在 Xcode 里打开 `*.xcodeproj` 文件。选中项目下 `AUIKitDemo` 文件夹,右键选择 **Add Files to "AUIKitDemo" ...**。 ![在 Xcode 中添加文件的入口示意图](https://web-cdn.agora.io/docs-portal/img/chatroom/import-1.png) 2. 指定 `AUIVoiceRoom/iOS/AUIVoiceRoom/AUIVoiceRoom/VoiceChatUIKit.swift` 文件,勾选 **Destination: Copy items if neeed**,点击右下角 **Add**。 ![选择 VoiceChatUIKit.swift 并添加到项目的示意图](https://web-cdn.agora.io/docs-portal/img/chatroom/import-2.png) 5. 在终端里进入 `*.xcodeproj` 文件所在目录,并运行 `pod init` 命令。项目文件夹下会生成一个 `Podfile` 文本文件。 6. 打开 `Podfile` 文件,修改文件为如下内容。注意 `target` 和 `path` 的填写。 ```ruby source 'https://github.com/CocoaPods/Specs.git' platform :ios, '13.0' # target 需改为你的项目中实际的 Target 名称 target 'AUIKitDemo' do use_frameworks! # path 需为 AScenesKit 依赖库的实际路径 pod 'AScenesKit', :path => './AScenesKit' # 推荐你指定 RTC SDK 版本为 4.1.1.20 pod 'AgoraRtcEngine_Special_iOS', '4.1.1.20' end post_install do |installer| installer.pods_project.targets.each do |target| target.build_configurations.each do |config| config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '13.0' end end end ``` 7. 在终端里进入 `*.xcodeproj` 文件所在目录,运行如下命令安装 AUIKit 依赖: ```shell pod update --verbose ``` ![](https://web-cdn.agora.io/docs-files/1697696810206) ![](https://web-cdn.agora.io/docs-files/1697696820778) ![](https://web-cdn.agora.io/docs-files/1697696829568) 如果等待安装的时间太久,请参考[加速 Pod](#加速-pod)。依赖库安装成功后,与 `*.xcodeproj` 文件所在的同一级目录下会出现一个 `*.xcworkspace` 文件。打开该文件即可体验安装了 AScenesKit 和 AUIKit 等依赖的项目。 完成上述步骤后,你的项目文件夹结构如下: ## 实现语聊房 [#实现语聊房-1] `VoiceChatUIKit` 基于声网 RTC、RTM 引擎、AUIKit 等模块封装,帮助你轻松管理语聊房。 你可以使用 `VoiceChatUIKit` 类中的 API 实现语聊房间的创建和销毁、用户进房和退房等功能。 ### 1. 初始化 VoiceChatUIKit [#1-初始化-voicechatuikit] 本节展示初始化 `VoiceChatUIKit` 的代码逻辑: 1. 在 `AppDelegate.swift` 文件里导入依赖库: ```swift import AUIKitCore import AScenesKit ``` 2. 在 `AppDelegate` 类中调用 `VoiceChatUIKit` 类的 `setup` 方法并传入如下参数,初始化 `VoiceChatUIKit`: - `commonConfig`:基础配置,包含如下参数: - `ownerInfo`:设置你的业务的用户信息。 - 声网项目的 App ID。 - 声网项目的 App 证书。 - 用于 HTTP 基本认证的 `Authorization`。 - 环信 IM 服务的 App Key。 - 环信 IM 服务的 Client ID。 - 环信 IM 服务的 Client Secret。 - 语聊后端服务的 Host URL。 App ID 等参数取值可参考[配置示例项目](/zh-CN/solutions/chatroom/uikit/build/run-github-project#配置示例项目)。 - `apiConfig`:声网 API 实例结构体,包含 RTC 引擎和 RTM 引擎实例。如需使用其中任一一个实例,请通过该结构体进行传入,如果未传入,系统内部会自动创建。 ```swift func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // 生成一个随机的用户 ID let uid = Int(arc4random_uniform(99999999)) // 将基础配置信息传入 VoiceChatUIKit let commonConfig = AUICommonConfig() commonConfig.appId = KeyCenter.AppId commonConfig.appCert = KeyCenter.AppCertificate commonConfig.basicAuth = KeyCenter.AppBasicAuth commonConfig.imAppKey = KeyCenter.IMAppKey commonConfig.imClientId = KeyCenter.IMClientId commonConfig.imClientSecret = KeyCenter.IMClientSecret commonConfig.host = KeyCenter.HostUrl let ownerInfo = AUIUserThumbnailInfo() ownerInfo.userId = "\(uid)" ownerInfo.userName = "user_\(uid)" ownerInfo.userAvatar = "https://accktvpic.oss-cn-beijing.aliyuncs.com/pic/sample_avatar/sample_avatar_1.png" commonConfig.owner = ownerInfo VoiceChatUIKit.shared.setup(commonConfig: commonConfig, apiConfig: nil) ... return true } ``` ### 2. 房主创建并加入房间 [#2-房主创建并加入房间-1] 本节展示如何让房主创建并加入语聊房。 #### 2.1 添加按钮:创建房间 [#21-添加按钮创建房间-1] 在 `ViewController.swift` 文件里导入依赖库: ```swift import AUIKitCore import AScenesKit ``` 在 `ViewController` 类中,通过 iOS 原生方法增加一个**创建房间**按钮,用于让房主点击创建。 ```swift override func viewDidLoad() { super.viewDidLoad() // 作为房主创建房间的按钮 let createButton = UIButton(frame: CGRect(x: 10, y: 100, width: 100, height: 60)) createButton.setTitle("创建房间", for: .normal) createButton.setTitleColor(.red, for: .normal) createButton.addTarget(self, action: #selector(onCreateAction), for: .touchUpInside) view.addSubview(createButton) } ``` #### 2.2 声明属性 [#22-声明属性] 在 `ViewController` 类中声明了一个可选属性,用于存储 `AUIVoiceChatRoomView` 实例以显示语聊房的详情界面。 ```swift class ViewController: UIViewController { var voiceChatView: AUIVoiceChatRoomView? ... } ``` #### 2.3 创建房间详情页并启动房间 [#23-创建房间详情页并启动房间] 在 `ViewController` 中,创建一个 `AUIVoiceChatRoomView` 实例,并将它设置为 `voiceChatView` 属性,用于显示语聊房的详情界面。 在 `ViewController` 的创建房间点击回调(`onCreateAction`)里,调用 `VoiceChatUIKit` 类的 `createRoom` 方法,并传入以下参数,以启动语聊房: - `roomInfo`:房间信息。包含如下: - `roomId`:房间 ID,每个房间的唯一标识。 - `roomName`:房间名称。不同房间的名称可以重名。 - `owner`:房主信息。 - `roomConfig`:房间配置,包含房间名、Token 等配置。你可以使用自己的 Token 后台服务生成 Token。 - `voiceChatView`:房间的 UI View。 ```swift @objc func onCreateAction(_ button: UIButton) { // 禁用按钮,防止重复点击 button.isEnabled = false // 生成一个随机的房间 ID let roomId = Int(arc4random_uniform(99999999)) // 创建一个 RoomInfo 实例 let roomInfo = AUIRoomInfo() roomInfo.roomId = "\(roomId)" roomInfo.roomName = "\(roomId)" roomInfo.owner = AUIRoomContext.shared.currentUserInfo let roomConfig = AUIRoomConfig() // 创建房间容器 let voiceChatView = AUIVoiceChatRoomView(frame: self.view.bounds) generateToken(channelName: "\(roomId)", roomConfig: roomConfig, completion: {[weak self] error in guard let self = self else { return } defer { // 恢复按钮可用状态 button.isEnabled = true } if let error = error { self.navigationController?.popViewController(animated: true) AUIToast.show(text: error.localizedDescription) return } // 创建房间 VoiceChatUIKit.shared.createRoom(roomInfo: roomInfo, roomConfig: roomConfig, chatView: voiceChatView) {[weak self] error in guard let self = self else { return } if let error = error { // 创建房间失败 AUIToast.show(text: error.localizedDescription) return } } }) self.view.addSubview(voiceChatView) self.voiceChatView = voiceChatView } private func generateToken(channelName: String, roomConfig: AUIRoomConfig, completion: @escaping ((Error?) -> Void)) { let uid = VoiceChatUIKit.shared.commonConfig?.owner?.userId ?? "" let rtcChorusChannelName = "\(channelName)_rtc_ex" roomConfig.channelName = channelName roomConfig.rtcChorusChannelName = rtcChorusChannelName print("generateTokens: \(uid)") let group = DispatchGroup() var err: Error? group.enter() let tokenModel1 = AUITokenGenerateNetworkModel() tokenModel1.channelName = channelName tokenModel1.userId = uid tokenModel1.request { error, result in defer { if err == nil { err = error } group.leave() } guard let tokenMap = result as? [String: String], tokenMap.count >= 2 else { return } roomConfig.rtcToken = tokenMap["rtcToken"] ?? "" roomConfig.rtmToken = tokenMap["rtmToken"] ?? "" } group.enter() let tokenModel2 = AUITokenGenerateNetworkModel() tokenModel2.channelName = rtcChorusChannelName tokenModel2.userId = uid tokenModel2.request { error, result in defer { if err == nil { err = error } group.leave() } guard let tokenMap = result as? [String: String], tokenMap.count >= 2 else { return } roomConfig.rtcChorusRtcToken = tokenMap["rtcToken"] ?? "" } group.notify(queue: DispatchQueue.main) { completion(err) } } ``` ### 3. (可选)听众加入房间 [#3-可选听众加入房间-1] 本节展示如何让听众加入已存在的房间。 #### 3.1 添加按钮:加入房间 [#31-添加按钮加入房间-1] 在 `ViewController` 类中,通过 iOS 原生方法增加一个**加入房间**按钮,用于让听众点击加入。 ```swift override func viewDidLoad() { super.viewDidLoad() // 作为房主创建房间的按钮 let createButton = UIButton(frame: CGRect(x: 10, y: 100, width: 100, height: 60)) createButton.setTitle("创建房间", for: .normal) createButton.setTitleColor(.red, for: .normal) createButton.addTarget(self, action: #selector(onCreateAction), for: .touchUpInside) view.addSubview(createButton) // highlight-start // 作为听众加入房间的按钮 let joinButton = UIButton(frame: CGRect(x: 10, y: 160, width: 100, height: 60)) joinButton.setTitle("加入房间", for: .normal) joinButton.setTitleColor(.red, for: .normal) joinButton.addTarget(self, action: #selector(onJoinAction), for: .touchUpInside) view.addSubview(joinButton) // highlight-end } ``` #### 3.2 获取房间列表 [#32-获取房间列表-1] 在 `ViewController` 类中,调用 `VoiceChatUIKit` 类的 `getRoomInfoList` 方法并传入如下参数,以获取语聊房间列表: - `lastCreateTime`:房间列表的起始时间(毫秒)。例如,1681879844085。 - `pageSize`:每一页房间列表所展示的房间数量。 如果在房间列表中找到匹配的房间名,并获取到对应的 `roomInfo` 信息,则执行 `enterRoom` 函数。 ```swift @objc func onJoinAction() { // 创建 UIAlertController 实例,用于显示弹出对话框 let alertController = UIAlertController(title: "房间名", message: "", preferredStyle: .alert) alertController.addTextField { (textField) in textField.placeholder = "请输入" } // 创建一个「取消」按钮,并指定点击事件 let cancelAction = UIAlertAction(title: "取消", style: .cancel) { (_) in } // 创建一个「确认」按钮,并指定点击事件 let saveAction = UIAlertAction(title: "确认", style: .default) { (_) in // 获取用户输入的文本内容 if let inputText = alertController.textFields?.first?.text { // 处理用户输入的内容 VoiceChatUIKit.shared.getRoomInfoList(lastCreateTime: 0, pageSize: 50) { error, roomList in // 检查是否有错误发生,并确保成功获取到了房间列表 guard let roomList = roomList else { return } // 遍历房间列表 for room in roomList { // 比对房间名与用户输入的文本内容是否匹配 if room.roomName == inputText { // 找到匹配的房间名,执行 enterRoom 函数 self.enterRoom(roomInfo: room) // 结束循环 break } } } } } // 将「取消」按钮添加到弹出对话框 alertController.addAction(cancelAction) // 将「确认」按钮添加到弹出对话框 alertController.addAction(saveAction) // 在当前视图上显示弹出对话框 present(alertController, animated: true, completion: nil) } ``` #### 3.3 听众加入房间 [#33-听众加入房间-1] 在上一步获取到房间信息后,调用 `VoiceChatUIKit` 类的 `enterRoom` 方法并传入如下参数,即可加入房间并显示房间数据: - `roomId`:房间 ID,每个房间的唯一标识。 - `roomConfig`:房间配置,包含房间名、Token 等配置。你可以使用自己的 Token 后台服务生成 Token。 - `chatView`:房间的 UI View。 ```swift func enterRoom(roomInfo: AUIRoomInfo) { // 创建一个 AUIVoiceChatRoomView 实例,并设置其 frame 为当前视图的边界 let voiceChatView = AUIVoiceChatRoomView(frame: self.view.bounds) let roomId = roomInfo.roomId let roomConfig = AUIRoomConfig() generateToken(channelName: roomId, roomConfig: roomConfig) {[weak self] err in guard let self = self else {return} // 调用 enterRoom 方法加入房间 VoiceChatUIKit.shared.enterRoom(roomId: roomId, roomConfig: roomConfig, chatView: self.voiceChatView!) {[weak self] roomInfo, error in guard let self = self else {return} if let error = error { // 如果出现错误,直接返回 self.navigationController?.popViewController(animated: true) AUIToast.show(text: error.localizedDescription) return } } } self.view.addSubview(voiceChatView) self.voiceChatView = voiceChatView } ``` ### 4. (可选)退出或销毁房间 [#4-可选退出或销毁房间-1] 本节展示如何退出并销毁房间。 在语聊房中,房主可以主动销毁房间,房间销毁时听众会被动退出房间。房间存在时,听众可以主动退出房间,也可以被房主踢出房间。下面从主动和被动的角度展示代码逻辑: #### 4.1 主动退出或销毁房间 [#41-主动退出或销毁房间-1] 在 `ViewController` 类里 `enterRoom` 函数中,`let voiceChatView = AUIVoiceChatRoomView(frame: self.view.bounds)` 代码后添加如下高亮的几行,以实现通过点击按钮,让听众主动退出房间。 ```swift func enterRoom(roomInfo: AUIRoomInfo) { // 创建一个 AUIVoiceChatRoomView 实例,并设置其 frame 为当前视图的边界 let voiceChatView = AUIVoiceChatRoomView(frame: self.view.bounds) // highlight-start // 听众点击按钮主动退出房间 voiceChatView.onClickOffButton = { [weak self] in self?.destroyRoom(roomId: roomInfo.roomId) } // highlight-end ... } ``` 在 `ViewController` 类里 `onCreateAction` 函数中,`let voiceChatView = AUIVoiceChatRoomView(frame: self.view.bounds)` 代码后添加如下高亮的几行,以实现通过点击按钮,让房主销毁房间。 ```swift @objc func onCreateAction(_ button: UIButton) { ... // 创建房间容器 let voiceChatView = AUIVoiceChatRoomView(frame: self.view.bounds) // highlight-start // 房主点击按钮销毁房间 voiceChatView.onClickOffButton = { [weak self] in self?.destroyRoom(roomId: roomInfo.roomId) } // highlight-end ... } ``` #### 4.2 被动退出房间 [#42-被动退出房间-1] 听众被动退出房间的代码逻辑如下: 1. 在 `ViewController` 类里 `onCreateAction` 函数中,`createRoom` 方法后添加如下高亮行。调用 `VoiceChatUIKit` 类的 `bindRespDelegate` 方法,订阅房间被销毁的回调。 ```swift @objc func onCreateAction(_ button: UIButton) { ... generateToken(channelName: "\(roomId)", roomConfig: roomConfig, completion: {[weak self] error in ... VoiceChatUIKit.shared.createRoom(roomInfo: roomInfo, roomConfig: roomConfig, chatView: voiceChatView) {[weak self] error in ... } // highlight-start // 订阅房间被销毁回调 VoiceChatUIKit.shared.bindRespDelegate(delegate: self) // highlight-end }) ... } ``` 2. 在 `ViewController` 类里 `enterRoom` 函数中,`VoiceChatUIKit.shared.enterRoom(...){...}` 代码后添加如下高亮行。调用 `VoiceChatUIKit` 类的 `bindRespDelegate` 方法,订阅房间被销毁的回调。 ```swift func enterRoom(roomInfo: AUIRoomInfo) { ... generateToken(channelName: roomId, roomConfig: roomConfig) {[weak self] err in guard let self = self else {return} VoiceChatUIKit.shared.enterRoom(roomId: roomId, roomConfig: roomConfig, chatView: self.voiceChatView!) {[weak self] roomInfo, error in ... } // highlight-start // 订阅房间被销毁回调 VoiceChatUIKit.shared.bindRespDelegate(delegate: self) // highlight-end } ... } ``` 3. 在 `ViewController` 文件中,通过 `AUIVoiceChatRoomServiceRespDelegate` 监听如下事件: - `onRoomDestroy`:房间被房主销毁事件。 - `onRoomUserBeKicked`:听众被房主踢出房间时间。 当监听到这些事件时,执行 `destroyRoom` 函数。 ```swift extension ViewController: AUIVoiceChatRoomServiceRespDelegate { // 房间销毁回调 @objc func onRoomDestroy(roomId: String) { self.destroyRoom(roomId: roomId) } // 听众被房主踢出房间回调 @objc func onRoomUserBeKicked(roomId: String, userId: String) { self.destroyRoom(roomId: roomId) } } ``` 4. 在 `ViewController` 类中,增加 `destroyRoom` 函数。在该函数中,调用 `VoiceChatUIKit` 类的 `unbindRespDelegate` 方法,取消订阅房间被销毁的回调。这样,在房间销毁时,将不再接收房间相关事件。 ```swift func destroyRoom(roomId: String) { // 在退出房间时取消订阅,调用 VoiceChatUIKit 的 unbindRespDelegate 方法 VoiceChatUIKit.shared.unbindRespDelegate(delegate: self) } ``` #### 4.3 补全销毁逻辑 [#43-补全销毁逻辑-1] 在[主动退出或销毁房间](#41-主动退出或销毁房间-1)、[被动退出房间](#42-被动退出房间-1)的情况下,都会执行 `destroyRoom` 函数。 在 `destroyRoom` 函数中,添加如下高亮的几行。调用 `VoiceChatUIKit` 类的 `leaveRoom` 方法并传入房间 ID,以退出或销毁房间。至此,`destroyRoom` 函数的代码补全。 ```swift func destroyRoom(roomId: String) { // highlight-start // 点击退出,调用 VoiceChatView 的 onBackAction 方法 self.voiceChatView?.onBackAction() // 将 VoiceChatView 从父视图中移除 self.voiceChatView?.removeFromSuperview() // 调用 VoiceChatUIKit 的 leaveRoom 方法退出房间(听众)或销毁房间(主播) VoiceChatUIKit.shared.leaveRoom(roomId: roomId) // highlight-end // 在退出房间时取消订阅,调用 VoiceChatUIKit 的 unbindRespDelegate 方法 VoiceChatUIKit.shared.unbindRespDelegate(delegate: self) } ``` ## 注意事项 [#注意事项-1] ### 加速 Pod [#加速-pod] 为加速 Pod 命令的执行结果,建议你使用国内镜像源,步骤如下: 1. 打开 `Podfile` 文件,更改 source 为国内镜像源 ```shell # 移除官方源 # source 'https://github.com/CocoaPods/Specs.git' # 使用国内镜像源 source 'https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git' ``` 2. 保存并退出 `Podfile`,重新执行 Pod 命令安装依赖库。 ### 问题排查 [#问题排查] 如果在 Xcode 15 编译项目时遇到 `Sandbox: rsync.samba(47334) deny(1) file-write-create...` 报错信息,你可以依次进行如下操作: 1. 在 Xcode 中选中 **PROJECT**,点击 **Build Settings**,在 Filter 搜索框中搜索 User Script Sandboxing,将该选项设为 **No**。 2. 选中 **TARGETS**,检查并确保 **User Script Sandboxing** 的设置为 **No**。 ![Xcode User Script Sandboxing 设置示意图](https://web-cdn.agora.io/docs-files/1697685882007) ### 后端部署 [#后端部署] 声网在示例项目中提供的后端服务 Host URL(`https://service.shengwang.cn/uikit-v2`)仅供测试和快速集成语聊房使用,请勿用于商业用途。如需商用,请自行部署后端服务,并将客户端代码中的声网后端服务 Host URL 更新为你的服务 Host URL,详见[部署后端服务](/zh-CN/solutions/chatroom/uikit/build/run-github-project-backend)。 ## 下一步 [#下一步-1] 在创建、进入房间后,你可以参考如下业务流程图开发后续的麦位管理、聊天、礼物等功能。