# 实现语聊房 (/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。

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" ...**。

2. 指定 `AUIVoiceRoom/iOS/AUIVoiceRoom/AUIVoiceRoom/VoiceChatUIKit.swift` 文件,勾选 **Destination: Copy items if neeed**,点击右下角 **Add**。

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
```



如果等待安装的时间太久,请参考[加速 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**。

### 后端部署 [#后端部署]
声网在示例项目中提供的后端服务 Host URL(`https://service.shengwang.cn/uikit-v2`)仅供测试和快速集成语聊房使用,请勿用于商业用途。如需商用,请自行部署后端服务,并将客户端代码中的声网后端服务 Host URL 更新为你的服务 Host URL,详见[部署后端服务](/zh-CN/solutions/chatroom/uikit/build/run-github-project-backend)。
## 下一步 [#下一步-1]
在创建、进入房间后,你可以参考如下业务流程图开发后续的麦位管理、聊天、礼物等功能。