跳到主要内容

离线语音助手鉴权

可选的 AIBudsVoiceAssistant 模块为受支持设备的离线语音助手执行鉴权。该鉴权桥接不同于在离线语音助手中选择禁用、基础或高级运行模式。

Animated workflow

离线语音助手鉴权

仅当已连接的受支持设备需要鉴权时，Core 才会触发已注册插件。

设备 + Core

连接设备

完成正常的受支持设备连接流程。

AIBuds Core

检测鉴权需求

Core 判断是否需要语音助手鉴权。

Voice Assistant

启动插件

将设备身份传给已注册的语音助手桥接。

插件 ↔ 设备

交换不透明数据

转发加密鉴权数据，宿主 App 不进行解析。

桥接传输
宿主 App

接收鉴权结果

通过 SDK 或设备 Delegate 接收成功状态或错误。

桥接数据发送成功只代表传输完成；最终鉴权结果以 Delegate 回调为准。

鉴权流程​

Core 设备实现决定何时需要鉴权。已注册的 OnDeviceVoiceAssistantBridgePlugin 通过 OnDeviceVoiceAssistantDevice 交换不透明桥接数据。宿主 App 只处理最终结果，不得解析、持久化或修改桥接数据。

使用 AI 辅助实现

使用 AI 开发

让 AI 帮助实现此工作流

使用官方“管理 AIBuds 设备端语音助手”技能，根据你的 App 完成实现。

请阅读并遵循 https://docs-aibuds.github.io/zh-Hans/skills/manage-aibuds-on-device-voice-assistant，使用该技能在当前 iOS 项目中完成“管理 AIBuds 设备端语音助手”，并验证结果。
查看官方技能

注册桥接插件​

AIBudsAllInOneSDK.initialize 会注册 OnDeviceVoiceAssistantPlugin.shared。模块化集成必须包含 AIBudsVoiceAssistant，并在连接设备前注册该桥接。注册应与 Core 初始化由同一个应用级对象负责。

SDK 没有面向应用的“立即鉴权”手动功能 API。当 SDK 判断需要鉴权时，由受支持设备的连接流程触发。

处理最终鉴权结果​

实现 SDK 或设备 Delegate 回调：

Swift
func device(
    _ device: DeviceConvertible,
    didReceiveOnDeviceVoiceAssistantAuthResult isSuccess: Bool,
    error: NSError?
) {
    // Update product state on the main queue.
}

宿主 App 应以该回调判断最终鉴权结果。桥接数据发送成功只表示传输完成，不代表鉴权成功。

顺序与重试​

如果设备还需要另一个 AI 鉴权桥接，SDK 可能在前一个鉴权结果之后再执行离线语音助手鉴权。不要从 UI 代码启动相互竞争的鉴权尝试。

当前公开契约未定义手动重试 API、超时时间、持久化鉴权有效期或完整错误码恢复表。失败时请保留错误用于诊断；如果产品策略要求鉴权，则保持语音助手模式不可用，并由已公开的重连流程或未来 SDK 重试契约控制下一次尝试。

安全边界​

  • 将桥接数据视为不透明凭据材料。
  • 生产环境中切勿记录载荷字节、设备身份或派生密钥。
  • 不要缓存或重放桥接数据包。
  • 保持插件及其加密依赖与 SDK 版本匹配。
  • 只向用户显示可操作的失败状态；详细错误保留在受保护诊断中。

验证清单​

  • 连接设备前已注册桥接插件。
  • 未混用 All-in-One 与模块化注册。
  • UI 等待最终 Delegate 回调。
  • 宿主 App 既不解析也不持久化桥接数据包。
  • 鉴权失败不会静默启用需要鉴权的语音助手模式。
  • 已在各受支持设备系列上测试断开和重连行为。