For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 角色可以看到并回应您在模拟过程中展示的内容。

运行时权限处理

SDK 不会自动请求麦克风权限。在开始对话之前,您的应用必须已获得麦克风权限——如果 SDK 启动麦克风时权限缺失,它会抛出 InvalidOperationException。请在应用初始化期间、首次尝试对话之前请求权限。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 会在构建时将其与生成的 manifest 合并。

构建后,请验证权限是否出现在导出的 AndroidManifest.xml 中的 APK 或 AAB 内——如果文件格式不正确,Unity 的 manifest 合并有时会遗漏条目。

运行时权限处理

SDK 不会自动请求麦克风权限。在开始对话之前,您的应用必须已获得 RECORD_AUDIO 运行时权限——如果 SDK 启动麦克风时权限缺失,它会抛出 InvalidOperationException。调用 Permission.RequestUserPermission(Permission.Microphone, callbacks) 在应用初始化期间,并在启动会话前等待回调。与 iOS 不同,Android 允许重复请求权限。两次拒绝后,Android 可能会显示“Don’t ask again”选项,此后 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 是否出现在导出的 manifest 中。

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

移动端 Vision

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

在 iOS 上,Vision 需要 NSCameraUsageDescription 在 Player Settings 中——该组件会调用 Application.RequestUserAuthorization(UserAuthorization.WebCam) 在运行时自动请求该权限。在 Android 上,Vision 需要 android.permission.CAMERA 在 manifest 中——该组件会调用 Permission.RequestUserPermission(Permission.Camera) 在运行时自动请求。您无需手动请求摄像头权限;只需在 Player Settings(iOS)或 manifest(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" /> 添加到您的 manifest,并验证其是否出现在导出的 APK 中。

Android 上摄像头权限提示从未出现(Vision)

CAMERA 缺失于 AndroidManifest.xml

添加 <uses-permission android:name="android.permission.CAMERA" /> 添加到您的 manifest 中。

应用转入后台后麦克风停止工作

操作系统已暂停采集——预期行为

返回前台后 SDK 会自动恢复采集。无需操作。

iOS 提示在第二次启动时不出现

用户在首次启动时拒绝——iOS 不会再次提示

添加应用内消息,引导用户前往 设置 → 隐私与安全性 → 麦克风 以重新启用。使用 Application.HasUserAuthorization(UserAuthorization.Microphone) 来检测被拒绝状态。

下一步

一旦在真机上声明并测试了权限,您的 iOS 和 Android 构建就可以发布了。如果您还要部署到 XR 头显,这些构建还有额外的 Vision 要求。

XR 头显WebGL

最后更新于

这有帮助吗?