# 快速集成 UIKit 开源方案 (/zh-CN/solutions/online-ktv/auikaraoke/get-started/integrate/ios) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). AUIKaraoke 是一个基于 [AUIKit](https://github.com/AgoraIO-Community/AUIKit/blob/main/iOS) 搭建的、针对 K 歌场景的开源 UI 组件,提供 K 歌房间相关功能。AScenesKit 是 K 歌房的容器组件,你可以通过 AScenesKit 自定义 K 歌房间的界面逻辑,并实现房间管理等功能。 本文介绍如何通过 [AUIKaraoke](/zh-CN/solutions/online-ktv/auikaraoke/build/manage-karaoke/uikitkaraoke) 快速搭建一个含 UI 界面的在线 K 歌房。 ## 示例项目 [#示例项目-1] 声网在 GitHub 上提供一个开源的[示例项目](https://github.com/AgoraIO-Community/API-Examples-AUIKit/tree/main/iOS/KaraokeApp) 供你参考。 ## 准备开发环境 [#准备开发环境-1] 本节介绍集成 AUIKaraoke 的前提条件和项目相关配置。 ### 前提条件 [#前提条件-1] - [Git](https://git-scm.com/downloads) - [CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started) 1.12.1 及以上 - [Xcode](https://apps.apple.com/cn/app/xcode/id497799835?mt=12) 14.0 及以上 - iOS 设备,版本 13.0 及以上 :::info[信息] 声网推荐使用真机运行项目。部分模拟机可能存在功能缺失或者性能问题。 ::: - 有效的苹果开发者账号 - 你的声网项目的 App ID、App 证书,以及环信项目的 APPKEY、Client ID 以及 Client Secret,如何获取请参考[开通 UIKit 开源方案相关服务](/zh-CN/solutions/online-ktv/auikaraoke/build/setup-and-access/enable-service) ### 创建并配置项目 [#创建并配置项目] 按照下列步骤来创建并配置你的项目。 1. [创建一个新的项目](https://help.apple.com/xcode/mac/current/#/dev07db0e578),**Application** 选择 **App**,**Interface** 选择 **Storyboard**,**Language** 选择 **Swift**。 如果你没有添加过开发团队信息,会看到 **Add account…** 按钮。点击该按钮并按照屏幕提示登录 Apple ID,点击 **Next**,完成后即可选择你的 Apple 账户作为开发团队。 2. 为你的项目设置[自动签名](https://help.apple.com/xcode/mac/current/#/dev23aab79b4)。 3. 设置部署你的 App 的[目标设备](https://help.apple.com/xcode/mac/current/#/deve69552ee5)。 4. 添加项目的设备权限。在项目导航栏中 `info` 下,配置麦克风权限,如下图所示: ![](https://web-cdn.agora.io/docs-files/1697770935216) ### 添加依赖库 [#添加依赖库-1] 1. 下载声网提供的 [AUIKaraoke](https://github.com/AgoraIO-Community/AUIKaraoke) 源码。运行以下命令克隆项目到本地: ```shell git clone git@github.com:AgoraIO-Community/AUIKaraoke.git ``` 2. 将 AUIKaraoke 源码目录下 `iOS/AScenesKit` 文件夹复制到你的项目路径下,例如放在和 `AUIKitDemo.xcodeproj` 同级的目录下。 3. 将 AUIKaraoke 源码目录下 `iOS/Example/AUIKaraoke/KaraokeUIKit.swift` 类复制到你的项目路径下。 1. 选中项目下 `AUIKitDemo` 文件夹,右键选择 **Add Files to "AUIKitDemo"**。 2. 指定 `KaraokeUIKit.swift` 文件,勾选 **Destination: Copy items if neeed**,点击右下角 `Add`。 4. 在 `AUIKitDemo.xcodeproj` 同级目录下创建一个 Podfile 文件,并添加如下内容: ```ruby source 'https://github.com/CocoaPods/Specs.git' platform :ios, '13.0' target 'AUIKitDemo' do use_frameworks! pod 'AScenesKit', :path => './AScenesKit' pod 'AgoraRtcEngine_Special_iOS', '4.1.1.29' 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 ``` 5. 在 Podfile 文件目录下打开终端,执行下列命令来把 AScenesKit 的相关依赖集成进 App 中: ```shell pod update --verbose ``` 成功后,该目录下会新生成一个 `AUIKitDemo.xcworkspace` 文件。如果你在执行上述命令时因网络问题而失败,可尝试更换镜像源,详见[常见问题](/zh-CN/solutions/online-ktv/auikaraoke/get-started/integrate)。 6. 打开 `AUIKitDemo.xcworkspace` 文件,点击 **Start the active scheme** 来编译项目。如果你使用的 Xcode 15,在编译时可能遇到报错,可参考[常见问题](/zh-CN/solutions/online-ktv/auikaraoke/get-started/integrate)解决报错。 ## 创建在线 K 歌房 [#创建在线-k-歌房-1] 本节介绍如何以房主身份快速搭建一个在线 K 歌房来体验 K 歌场景。 ### 1. 初始化 AUIKaraoke [#1-初始化-auikaraoke-1] 1. 添加依赖。 在 `AppDelegate.swift` 文件中添加下列代码来添加依赖: ```swift import AUIKitCore import AScenesKit ``` 2. 初始化 KaraokeUIKit。 创建 `AUICommonConfig` 对象,并调用 `setup` 方法初始化 `KaraokeUIKit`。在 `AppDelegate.swift` 文件中添加下列代码: ```swift func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // 随机设置用户 uid let uid = Int(arc4random_uniform(99999999)) let commonConfig = AUICommonConfig() // 你的声网 AppID commonConfig.appId = KeyCenter.AppId // 你的声网 App 证书 commonConfig.appCert = KeyCenter.AppCertificate // 你的 IM AppKey commonConfig.imAppKey = KeyCenter.IMAppKey // 你的 IM Client ID commonConfig.imClientId = KeyCenter.IMClientId // 你的 IM Client Secret commonConfig.imClientSecret = KeyCenter.IMClientSecret // 你的业务服务器域名 commonConfig.host = KeyCenter.HostUrl let ownerInfo = AUIUserThumbnailInfo() // 用户 ID 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 KaraokeUIKit.shared.setup(commonConfig: commonConfig, // apiConfig 包含 KtvApi、RtcEngine、RtmClient 对象。如果你的项目中还未使用这几个对象,请传入 nil, AUIKaraoke 内部会自行创建 apiConfig: nil) return true } ``` ### 2. 创建并进入房间 [#2-创建并进入房间-1] 1. 在 `ViewController.swift` 文件中添加下列依赖: ```swift import AUIKitCore import AScenesKit ``` 2. 添加**创建房间**按钮。 在 `ViewController.swift` 文件中,将 `viewDidLoad` 替换为下列代码: ```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) } ``` 3. 在 `ViewController` 文件中声明一个在线 K 歌房间容器的属性。 ```swift class ViewController: UIViewController { var karaokeView: AUIKaraokeRoomView? .... } ``` 4. 生成启动房间所需的 RTC Token 和 RTM Token。在 `ViewController.swift` 文件中,将下列代码添加至 `viewDidLoad` 之后: ```swift // 生成并配置房间的 Token private func generateToken(channelName: String, roomConfig: AUIRoomConfig, completion: @escaping ((Error?) -> Void)) { // 获取当前用户的 ID let uid = KaraokeUIKit.shared.commonConfig?.owner?.userId ?? "" // 定义 RTC 合唱频道的名称 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 // 发起网络请求来生成 Token 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 // 发起网络请求来生成 Token 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) } } ``` 5. 创建房间详情页再调用 `createRoom` 创建并进入房间。在 `ViewController.swift` 文件中,将下列代码添加至 `viewDidLoad` 之后: ```swift @objc func onCreateAction(_ button: UIButton) { button.isEnabled = false // 生成一个随机的房间 ID let roomId = Int(arc4random_uniform(99999999)) let roomInfo = AUIRoomInfo() roomInfo.roomId = "\(roomId)" roomInfo.roomName = "\(roomId)" roomInfo.owner = AUIRoomContext.shared.currentUserInfo let roomConfig = AUIRoomConfig() // 创建房间容器 let karaokeView = AUIKaraokeRoomView(frame: self.view.bounds) // 生成进入房间所需的 Token generateToken(channelName: "\(roomId)", roomConfig: roomConfig, completion: {[weak self] error in guard let self = self else {return} if let error = error { button.isEnabled = true self.navigationController?.popViewController(animated: true) AUIToast.show(text: error.localizedDescription) return } // 创建房间 KaraokeUIKit.shared.createRoom(roomInfo: roomInfo, roomConfig: roomConfig, karaokeView: karaokeView) {[weak self] error in guard let self = self else {return} button.isEnabled = true if let error = error { AUIToast.show(text: error.localizedDescription) return } } }) // 将房间视图添加到当前视图 self.view.addSubview(karaokeView) self.karaokeView = karaokeView } ``` 至此,你已经成功创建一个在线 K 歌房。 ### 测试 App [#测试-app-1] 参考以下步骤来测试你的 App: 1. 将 iOS 设备连接至计算机。 2. 点击 **start the active scheme** 来运行你的项目,需等待几秒至 App 安装完成。 3. (可选)如果设备上弹出不受信任的开发者提示,则首先点击取消关闭该提示,然后在 iOS 设备上打开设置 > 通用 > VPN 与设备管理,在开发者 APP 中选择信任该开发者。 4. 安装成功后,你的 iOS 设备上会出现 **AUIKaraoke** App。打开 App,点击**创建房间**创建一个新的房间来体验在线 K 歌。 ## 后续步骤 [#后续步骤-1] 成功搭建一个在线 K 歌房间后,你还可以参考本节来进一步了解启动 K 歌房间后的后续步骤。 ### 听众进入房间 [#听众进入房间-1] 1. 添加**加入房间**按钮。 在 `ViewController` 文件中添加下列代码: ```swift override func viewDidLoad() { super.viewDidLoad() ... // 观众加入房间的按钮 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) } ``` 2. 获取房间信息并调用 `enterRoom` 加入房间。在 `ViewController` 文件中,将下列代码添加至 `func onCreateAction` 之后: ```swift @objc func onJoinAction() { 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 { // 处理用户输入的内容,获取房间信息列表 KaraokeUIKit.shared.getRoomInfoList(lastCreateTime: 0, pageSize: 50) { error, roomList in guard let roomList = roomList else {return} for room in roomList { if room.roomName == inputText { self.enterRoom(roomInfo: room) break } } } } } alertController.addAction(cancelAction) alertController.addAction(saveAction) present(alertController, animated: true, completion: nil) } // 进入房间 func enterRoom(roomInfo: AUIRoomInfo) { let karaokeView = AUIKaraokeRoomView(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} KaraokeUIKit.shared.enterRoom(roomId: roomId, roomConfig: roomConfig, karaokeView: karaokeView) {[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(karaokeView) self.karaokeView = karaokeView } ``` ### 退出及销毁房间 [#退出及销毁房间-1] 当你不再需要进行 K 歌时,调用 `leaveRoom` 销毁房间。调用 `unbindRespDelegate` 取消绑定对应房间的响应。取消后,将不再通知 `AUIRoomManagerRespDelegate` 对象与房间管理操作相关的结果或响应。 在 `ViewController` 文件中添加下列代码: ```swift func destroyRoom(roomId: String) { //点击退出 self.karaokeView?.onBackAction() self.karaokeView?.removeFromSuperview() KaraokeUIKit.shared.leaveRoom(roomId: roomId) //在退出房间时取消订阅 KaraokeUIKit.shared.unbindRespDelegate(delegate: self) } ``` - 当房间被销毁时,退出该房间。 调用 `bindRespDelegate` 来订阅房间相关事件。在销毁房间时,调用 `unbindRespDelegate` 取消订阅房间相关事件,然后通过 `onRoomDestroy` 来处理房间销毁。在`ViewController` 文件将下列代码添加至 `destroyRoom` 之后: ```swift class ViewController: UIViewController { @objc func onCreateAction(_ button: UIButton) { ... // 房主订阅房间被销毁回调 KaraokeUIKit.shared.bindRespDelegate(delegate: self) } func enterRoom(roomInfo: AUIRoomInfo) { ... // 听众订阅房间被销毁回调 KaraokeUIKit.shared.bindRespDelegate(delegate: self) } } extension ViewController: AUIKaraokeRoomServiceRespDelegate { //房间销毁 func onRoomDestroy(roomId: String) { self.destroyRoom(roomId: roomId) } } ``` - 主动退出房间。当你结束 K 歌并需要释放 K 歌房使用的所有资源时,退出并销毁当前房间。示例代码如下: ```swift @objc func onCreateAction(_ button: UIButton) { ... let karaokeView = AUIKaraokeRoomView(frame: self.view.bounds) karaokeView.onClickOffButton = { [weak self] in // 房主退出并销毁房间 self?.destroyRoom(roomId: roomInfo.roomId) } } func enterRoom(roomInfo: AUIRoomInfo) { ... let karaokeView = AUIKaraokeRoomView(frame: self.view.bounds) karaokeView.onClickOffButton = { [weak self] in // 听众退出房间 self?.destroyRoom(roomId: roomInfo.roomId) } } ``` ## 常见问题 [#常见问题] ### pod update 失败 [#pod-update-失败] 如果你在执行 `pod update` 命令时,因网络问题而失败,可尝试使用国内镜像源。 1. 打开 `Podfile` 文件,将 `source` 替换为国内镜像源: ```ruby source 'https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git' ``` 2. 保存文件,重新执行 `pod update` 命令。 ### 使用 Xcode 15 编译报错 [#使用-xcode-15-编译报错] 如果你使用 Xcode 15,在编译时可能遇到下列报错: ``` Sandbox: rsync.samba(47334) deny(1) file-write-create... ``` 你可以在导航栏的 **Build Settings** 中将 **User Script Sandboxing** 设为 `NO`,如下图所示: ![](https://web-cdn.agora.io/docs-files/1697794691823) ## API 参考 [#api-参考-1] - [AUIKaraoke Swift API](/zh-CN/api-reference/online-ktv)