> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/ios-and-android.md).

# iOS 和 Android

iOS 和 Android 构建使用原生传输路径。所有核心 SDK 功能——语音对话、口型同步、动作、情绪、空间音频和 Vision——在两个平台上的工作方式完全一致。唯一需要实现的工作是在构建发送到设备或应用商店之前，声明麦克风和摄像头访问的操作系统级权限。

### 功能支持

| 功能                                | iOS    | Android |
| --------------------------------- | ------ | ------- |
| 语音对话                              | ✅ 完整支持 | ✅ 完整支持  |
| 口型同步                              | ✅ 完整支持 | ✅ 完整支持  |
| 动作                                | ✅ 完整支持 | ✅ 完整支持  |
| 情绪                                | ✅ 完整支持 | ✅ 完整支持  |
| 长期记忆                              | ✅ 完整支持 | ✅ 完整支持  |
| 叙事设计                              | ✅ 完整支持 | ✅ 完整支持  |
| Vision（`WebcamVisionFrameSource`) | ✅ 完整支持 | ✅ 完整支持  |
| 空间音频                              | ✅ 完整支持 | ✅ 完整支持  |
| Unity `AudioSource` 播放            | ✅ 完整支持 | ✅ 完整支持  |
| 麦克风设备选择                           | ✅ 完整支持 | ✅ 完整支持  |
| 屏幕共享                              | ❌ 不支持  | ❌ 不支持   |

| 平台      | 支持的架构                         |
| ------- | ----------------------------- |
| iOS     | arm64（设备），x86\_64（模拟器）        |
| Android | arm64-v8a、armeabi-v7a、x86\_64 |

### iOS 设置

在你的应用可以请求麦克风或摄像头访问之前，iOS 需要用途说明字符串。请在以下位置设置它们 **项目设置 → Player → iOS → 其他设置 → 用途说明**.

| 键                              | 在以下情况下必需        | 建议的说明                                   |
| ------------------------------ | --------------- | --------------------------------------- |
| `NSMicrophoneUsageDescription` | 始终需要——所有语音交互都必需 | `此应用使用你的麦克风，以启用与 AI 训练角色的语音对话。`         |
| `NSCameraUsageDescription`     | 仅在启用 Vision 时需要 | `此应用使用你的摄像头，以便 AI 角色能够看到并回应你在模拟中展示的内容。` |

{% hint style="danger" %}
**省略 `NSMicrophoneUsageDescription` 会导致应用崩溃。** iOS 会抛出 `NSInvalidArgumentException` 当应用在没有该键的情况下尝试访问麦克风时。此崩溃会在首次对话尝试时于运行时发生，并会在审核期间触发 Apple App Store 拒绝。 `NSCameraUsageDescription` 在启用 Vision 时也存在同样的崩溃风险。
{% endhint %}

#### 运行时权限处理

SDK 不会自动请求麦克风权限。在开始对话之前，你的应用必须已获得麦克风权限——如果 SDK 启动麦克风时权限不存在，它会抛出 `InvalidOperationException`。请在应用初始化期间、首次对话尝试之前请求权限。iOS 每种权限类型只会显示一次权限提示——如果先前已授予或拒绝，后续启动会跳过提示。

{% hint style="warning" %}
**iOS 的一次性提示无法再次触发。** 如果用户拒绝了麦克风权限，iOS 不会再次显示提示。你的应用必须引导用户前往 **设置 → 隐私与安全 → 麦克风** 以手动重新启用访问权限。针对这种情况添加应用内消息——例如，通过 `Application.HasUserAuthorization(UserAuthorization.Microphone)` 在尝试启动会话之前显示说明。
{% endhint %}

在开始会话之前请求权限并检查结果：

```csharp
using UnityEngine;

public class MicPermissionCheck : MonoBehaviour
{
    private IEnumerator Start()
    {
        if (!Application.HasUserAuthorization(UserAuthorization.Microphone))
        {
            yield return Application.RequestUserAuthorization(UserAuthorization.Microphone);
        }

        if (!Application.HasUserAuthorization(UserAuthorization.Microphone))
        {
            // 用户拒绝。显示在 iOS 设置中重新启用的指引。
            ShowPermissionDeniedUI();
            yield break;
        }

        // 已授予权限——继续启动会话。
    }

    private void ShowPermissionDeniedUI()
    {
        // 显示指引，引导用户前往 iOS 设置。
    }
}
```

#### 示例：iOS 上启用 Vision 的外科咨询训练

一所医学院在 iPad Pro 上部署了一款患者问诊训练应用。住院医师与一个 Convai 患者角色进行口头互动练习。启用 Vision 后，该角色可以识别住院医师举起的实体道具——解剖模型和流程参考卡片。

**设置：**

1. 在 **项目设置 → Player → iOS → 其他设置 → 用途说明**中，设置：
   * `NSMicrophoneUsageDescription`: `此应用使用你的麦克风，以启用与 AI 训练角色的语音对话。`
   * `NSCameraUsageDescription`: `此应用使用你的摄像头，以便 AI 角色能够看到并回应你在模拟中展示的内容。`
2. 添加 `WebcamVisionFrameSource` 到场景中的一个 GameObject，并分配一个 `ConvaiVisionPublisher`.
3. 语音对话的标准 SDK 配置。

**结果：** 首次启动时，iOS 会先显示麦克风权限提示，然后显示摄像头权限提示。两者都授予后，住院医师与角色交谈，并将实体道具举到 iPad 摄像头前。角色会识别其所见内容，并以临床上合适的对话进行回应。

### Android 设置

在自定义的 `AndroidManifest.xml` 位于 `Assets/Plugins/Android/AndroidManifest.xml`。如果项目中不存在该文件，请创建它——Unity 会在构建时将其与生成的清单合并。

```xml
<!-- 所有语音交互都必需 -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />

<!-- 仅在启用 Vision 时必需 -->
<uses-permission android:name="android.permission.CAMERA" />
```

构建后，请验证权限是否出现在导出的 `AndroidManifest.xml` 中的 APK 或 AAB 里——如果文件格式有误，Unity 的清单合并有时会省略条目。

#### 运行时权限处理

SDK 不会自动请求麦克风权限。在开始对话之前，你的应用必须已获得 `RECORD_AUDIO` 运行时权限——如果 SDK 启动麦克风时权限不存在，它会抛出 `InvalidOperationException`。调用 `Permission.RequestUserPermission(Permission.Microphone, callbacks)` 在应用初始化期间，并在回调返回前不要启动会话。与 iOS 不同，Android 允许重复请求权限。在两次拒绝之后，Android 可能会显示“不要再询问”选项，此后 `Permission.RequestUserPermission` 将不起作用。请通过应用内指引将用户引导到设备设置来处理这种情况。

#### 示例：Android 上的现场安全合规演练

一家制造公司在发放给生产线员工的 Android 平板上部署了一款安全检查员培训应用。Convai 角色扮演安全审计员，以口头方式带领操作员完成设备检查流程。

**设置：**

1. 添加 `<uses-permission android:name="android.permission.RECORD_AUDIO" />` 到 `Assets/Plugins/Android/AndroidManifest.xml`.
2. 标准 SDK 配置——不启用 Vision，因此不需要摄像头权限。
3. 构建后，请验证 `RECORD_AUDIO` 是否出现在导出的清单中。

**结果：** 首次启动时，Android 会显示麦克风权限提示。用户授予访问权限后，Convai 角色开始检查对话。后续启动会跳过该提示。如果用户之前已拒绝权限，应用会引导他们前往设备设置。

### 移动端的 Vision

`WebcamVisionFrameSource` 可在 iOS 和 Android 上运行。将该组件添加到场景中的一个 GameObject，并分配一个 `ConvaiVisionPublisher`。如果所需权限缺失，Unity Inspector 会显示平台特定警告——请在构建前处理这些问题。

在 iOS 上，Vision 需要 `NSCameraUsageDescription` 在 Player Settings 中——该组件会调用 `Application.RequestUserAuthorization(UserAuthorization.WebCam)` 在运行时自动请求权限。在 Android 上，Vision 需要 `android.permission.CAMERA` 在清单中——该组件会调用 `Permission.RequestUserPermission(Permission.Camera)` 在运行时自动执行。你不需要手动请求摄像头权限；只需在 Player Settings（iOS）或清单（Android）中声明它即可。

当应用转入后台时，操作系统会自动暂停麦克风采集。返回前台后，SDK 会在无需开发者干预的情况下恢复采集。会话状态遵循生命周期配置中定义的重新连接规则。

### 故障排除

| 症状                            | 可能原因                                                 | 修复                                                                                                                      |
| ----------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| 首次语音尝试时应用崩溃（iOS）              | `NSMicrophoneUsageDescription` 在 Player Settings 中缺失 | 在其中添加键 **项目设置 → Player → iOS → 其他设置 → 用途说明**.                                                                           |
| Vision 启动时应用崩溃（iOS）           | `NSCameraUsageDescription` 在 Player Settings 中缺失     | 在其中添加键 **项目设置 → Player → iOS → 其他设置 → 用途说明**.                                                                           |
| 麦克风权限提示从不出现（Android）          | `RECORD_AUDIO` 缺失于 `AndroidManifest.xml`             | 添加 `<uses-permission android:name="android.permission.RECORD_AUDIO" />` 将其添加到你的清单中，并验证它出现在导出的 APK 中。                    |
| Android 上 Vision 的摄像头权限提示从不出现 | `CAMERA` 缺失于 `AndroidManifest.xml`                   | 添加 `<uses-permission android:name="android.permission.CAMERA" />` 添加到你的清单中。                                             |
| 应用进入后台后麦克风停止工作                | 操作系统已暂停采集——预期行为                                      | SDK 会在返回前台时自动恢复采集。无需任何操作。                                                                                               |
| 第二次启动时 iOS 提示未出现              | 用户在首次启动时拒绝了——iOS 不会再次提示                              | 添加应用内消息，引导用户前往 **设置 → 隐私与安全 → 麦克风** 以重新启用。使用 `Application.HasUserAuthorization(UserAuthorization.Microphone)` 来检测被拒绝状态。 |

### 下一步

一旦权限已声明并在实体设备上测试完毕，你的 iOS 和 Android 构建就可以分发了。如果你也在 XR 头显上部署，这些构建还会有额外的 Vision 要求。

{% content-ref url="/pages/eaa8f2e135526b94c0bfa16f39b4e7f1cc91ca79" %}
[XR 头显](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/xr-headsets.md)
{% endcontent-ref %}

{% content-ref url="/pages/6cfceeb85df8a63f5076c12cd7b38b5a932ed4e8" %}
[WebGL](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/webgl.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/ios-and-android.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.