# 跑通 UIKit 开源方案示例项目 (/zh-CN/solutions/online-ktv/auikaraoke/get-started/kit-demo)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<_PlatformTabsGroup>
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="android" />
声网在 GitHub 上提供一个开源的 [AUIKaraoke 示例项目](https://github.com/AgoraIO-Community/AUIKitKaraoke/tree/main)。本文介绍如何快速跑通该示例项目，体验在线 K 歌场景。
## 前提条件 [#前提条件]

- [Git](https://git-scm.com/downloads)
- Android API Level 24 及以上
- Android Studio 3.5 及以上
- Android 设备，版本 Android 7.0 及以上
- [Java Development Kit](https://www.oracle.com/java/technologies/javase-downloads.html) 17 及以上

  :::info[信息]
  - 声网推荐使用真机运行项目。部分模拟机可能存在功能缺失或者性能问题。
    - 本示例项目使用的 Java Development Kit 版本为 17，Gradle 版本为 7.2。如果你编译失败，请修改编译使用的 Java Development Kit 或 Gradle 版本。
  :::

## 操作步骤 [#操作步骤]

### 获取示例项目 [#获取示例项目]

运行以下命令克隆仓库到本地：

```shell
git clone git@github.com:AgoraIO-Community/AUIKaraoke.git
```

### 配置示例项目 [#配置示例项目]

参考[开通 UIKit 开源方案相关服务](/zh-CN/solutions/online-ktv/auikaraoke/build/setup-and-access/enable-service)获取你的声网项目的 App ID、证书，以及环信项目的 APPKEY、Client ID 以及 Client Secret，参考[部署后端服务](/zh-CN/solutions/online-ktv/auikaraoke/build/manage-karaoke/run-github-project-backend)获取你的项目的后端服务的 Host URL，然后将上述信息填入项目的 `local.properties` 文件。

:::info[信息]
你也可以使用声网提供的测试域名 [https://service.shengwang.cn/uikit-v2](https://service.shengwang.cn/uikit-v2) 来快速体验，但请勿用于正式生产环境中。
:::

```properties
SERVER_HOST=<=你的后端服务域名=>
AGORA_APP_ID=<=你的声网 AppID=>
AGORA_APP_CERT=<=你的声网 App 证书=>
IM_APP_KEY=<=你的环信 APPKEY=>
IM_CLIENT_ID=<=你的环信 Client ID=>
IM_CLIENT_SECRET=<=你的环信 Client Secret=>
```

### 编译并运行示例项目 [#编译并运行示例项目]

1. 开启 Android 设备的开发者选项，打开 USB 调试，通过 USB 连接线将 Android 设备接入电脑，并在 Android 设备选项中勾选你的 Android 设备。

2. 在 Android Studio 中，点击 **Sync Project with Gradle Files** 按钮，以让项目与 Gradle 文件同步。

3. 待同步成功后，点击 <InlineImage alt="运行" src="https://web-cdn.agora.io/docs-files/1687670569781" width={25} /> 开始编译。

4. 编译成功后，你的 Android 设备上会出现 **AUIKaraoke** App。

5. 打开 App，点击**创建房间**即可开始体验在线 K 歌。

   <DocsImage alt="在线 K 歌房界面" src="https://web-cdn.agora.io/docs-files/1696931506007" displayWidth="40%" />
<_PlatformProcessedMarker close="true" />

<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="ios" />
声网在 GitHub 上提供一个开源的 [AUIKaraoke 示例项目](https://github.com/AgoraIO-Community/AUIKitKaraoke/tree/main)。本文介绍如何快速跑通该示例项目，体验在线 K 歌场景。

## 前提条件 [#前提条件-1]

- [Git](https://git-scm.com/downloads)

- CocoaPods 1.12.1 及以上。如果你未安装 CocoaPods，请参考 [Getting Started with CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started)
  进行安装。

  :::info[信息]
  如果你的 CocoaPods 版本低于 1.12.1，在运行 `pod install` 命令时可能会报错，详见[常见问题](/zh-CN/solutions/online-ktv/auikaraoke/get-started/kit-demo)。
  :::

- [Xcode](https://apps.apple.com/cn/app/xcode/id497799835?mt=12) 13.0 及以上

- iOS 设备，版本 13.0 及以上

  :::info[信息]
  声网推荐使用真机运行项目。部分模拟机可能存在功能缺失或者性能问题。
  :::

- 有效的苹果开发者账号

## 操作步骤 [#操作步骤-1]

### 获取示例项目 [#获取示例项目-1]

运行以下命令克隆仓库到本地：

```shell
git clone git@github.com:AgoraIO-Community/AUIKaraoke.git
```

### 配置示例项目 [#配置示例项目-1]

1. 打开终端，在 `AUIKaraoke/iOS/Example` 目录下运行 `pod update` 命令来安装 SDK 和相关依赖。安装完成后，终端会显示 `Pod installation complete!`。使用 Xcode 打开项目文件夹下新生成的 `AUIKaraoke.xcworkspace` 文件。

2. 参考[开通 UIKit 开源方案相关服务](/zh-CN/solutions/online-ktv/auikaraoke/build/setup-and-access/enable-service)获取你的声网项目的 App ID、App 证书，以及环信项目的 APPKEY、Client ID 以及 Client Secret，参考[部署后端服务](/zh-CN/solutions/online-ktv/auikaraoke/build/manage-karaoke/run-github-project-backend)获取你的项目的后端服务的 Host URL，然后将上述信息填入项目的 `KeyCenter.swift` 文件并保存。

:::info[信息]
你也可以使用声网提供的测试域名 [https://service.shengwang.cn/uikit-v2](https://service.shengwang.cn/uikit-v2) 来快速体验，但请勿用于正式生产环境中。
:::

   ```swift
   static var HostUrl: String = <#你端后服务域名#>
   static var AppId: String = <#你的声网 AppID#>
   static var AppCertificate: String = <#你的声网App 证书#>
   static var IMAppKey: String = <#你的环信 APPKEY#>
   static var IMClientId: String = <#你的环信 Client ID#>
   static var IMClientSecret: String = <#你的环信 Client Secret#>
   ```

### 编译并运行示例项目 [#编译并运行示例项目-1]

1. 将 iOS 设备连接至电脑。

2. 在 Xcode 界面顶部的 **iOS Device** 选项中勾选你的 iOS 设备。

3. 在项目 **TARGETS** 下的 **Signing & Capabilities** 界面勾选 **Automatically manage signing**，然后在每一个 Target 下配置你的苹果开发者账号和 **Bundle Identifier**。

   ![](https://web-cdn.agora.io/docs-files/1696931617035)

4. 点击 **Start the active scheme** 开始编译。

5. （可选）如果设备上弹出不受信任的开发者提示，则首先点击取消关闭该提示，然后在 iOS 设备上打开**设置** > **通用** > **VPN 与设备管理**，在开发者 APP 中选择信任该开发者。

6. 编译成功后，你的 iOS 设备上会安装好 AUIKaraoke App。打开 App，点击创建房间即可开始体验在线 K 歌。

   <DocsImage alt="在线 K 歌房界面" src="https://web-cdn.agora.io/docs-files/1696931506007" displayWidth="40%" />

<a id="reference"></a>
## 常见问题 [#常见问题]

本节提供跑通示例项目时可能遇到的常见问题及解决方案。

### Xcode 与 CocoaPods 版本不兼容 [#xcode-与-cocoapods-版本不兼容]

如果你的 Xcode 与 CocoaPods 版本不兼容，在跑通本示例项目时可能遇到如下报错：

```shell
can't modify frozen string: "[Xcodeproject] unknown object version (56).
```

### 解决方案 [#解决方案]

**方案一**

请确保将 **Minimum Deployments** 设为 **13.0**，**Project Document** 下的 **Project Format** 设为 **Xcode 13.0-compatible**，如下图所示：

![](https://web-cdn.agora.io/docs-files/1697796325100)

**方案二**

1. 升级 CocoaPods 版本。你可以通过运行下列命令来安装特定版本的 CocoaPods：

   ```shell
   # 指定你需要升级的 CocoaPods 版本，下列命令以 1.12.1 为例。
   gem install cocoapods -v 1.12.1
   ```

2. （可选）重置 CocoaPods 缓存。有时候 CocoaPods 缓存可能导致问题，你可以通过运行以下命令来清除缓存。

   ```shell
   pod cache clean --all
   ```

3. 在 `AUIKitKaraoke/iOS/Example` 目录下重新运行 `pod install` 命令来安装 SDK 和相关依赖。安装完成后，终端会显示 `Pod installation complete!`。
<_PlatformProcessedMarker close="true" />
</_PlatformTabsGroup>