> 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 构建声明麦克风和摄像头权限——遗漏它们会导致 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）中声明它即可。

当应用切换到后台时，OS 会自动挂起麦克风采集。回到前台后，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" />` 到你的清单中。                                             |
| 应用进入后台后麦克风停止工作               | OS 挂起了采集——这是预期行为                                   | 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, and the optional `goal` 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>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.