> 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 要求在应用请求麦克风或摄像头访问权限之前，设置用途说明字符串。请在以下位置设置： **Project Settings → Player → iOS → Other Settings → Usage Descriptions**.

| 键                              | 必需条件              | 建议的说明                                                                                                       |
| ------------------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------- |
| `NSMicrophoneUsageDescription` | 始终需要——所有语音交互均需此权限 | `This app uses your microphone to enable voice conversations with AI training characters.`                  |
| `NSCameraUsageDescription`     | 仅在启用 Vision 时需要   | `This app uses your camera so the AI character can see and respond to what you show during the simulation.` |

{% 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`: `This app uses your microphone to enable voice conversations with AI training characters.`
   * `NSCameraUsageDescription`: `This app uses your camera so the AI character can see and respond to what you show during the simulation.`
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" />
```

构建完成后，请检查导出的 APK 或 AAB 中是否包含这些权限，具体查看其中的 `AndroidManifest.xml` — 如果清单文件格式不正确，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 检视面板会显示特定于平台的警告——请在构建前处理这些问题。

在 iOS 上，Vision 需要在 Player Settings 中配置 `NSCameraUsageDescription` ——该组件会在运行时自动调用 `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 头显](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/xr-headsets.md)
{% endcontent-ref %}

{% content-ref url="/pages/6cfceeb85df8a63f5076c12cd7b38b5a932ed4e8" %}
[WebGL](https://docs.convai.com/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
