Skip to main content

On-Device Voice Assistant Authentication

The optional AIBudsVoiceAssistant module authenticates a supported device for its on-device voice assistant. This authentication bridge is distinct from selecting the assistant's disabled, basic, or advanced operating mode under Voice Assistant.

Animated workflow

On-device assistant authentication

Core triggers the registered plugin only when a connected supported device requires authentication.

Device + Core

Connect Device

Complete the normal supported-device connection flow.

AIBuds Core

Detect Requirement

Core determines whether assistant authentication is required.

Voice Assistant

Start Plugin

Pass device identity to the registered voice assistant bridge.

Plugin ↔ device

Exchange Opaque Data

Relay encrypted authentication data without host parsing.

bridge traffic
Host app

Receive Final Result

Deliver success or error through the SDK/device delegate.

Successful bridge transport is intermediate progress. The delegate authentication result is the terminal host-app signal.

Authentication Flow​

The Core device implementation decides when authentication is required. The registered OnDeviceVoiceAssistantBridgePlugin exchanges opaque bridge data through an OnDeviceVoiceAssistantDevice. The host app observes the final result; it must not parse, persist, or modify bridge payloads.

Implement with AI Assistance

Build with AI

Implement this workflow with AI

Use the official Manage AIBuds On-Device Voice Assistant skill to adapt this workflow to your app.

Read and follow https://docs-aibuds.github.io/skills/manage-aibuds-on-device-voice-assistant. Use it to implement Manage AIBuds On-Device Voice Assistant in this iOS project and verify the result.
View official skill

Registration Ownership​

AIBudsAllInOneSDK.initialize registers OnDeviceVoiceAssistantPlugin.shared. A modular integration must include AIBudsVoiceAssistant and register that bridge before connecting a device. Keep registration at the same application-level owner as Core initialization.

There is no app-facing manual “authenticate now” feature API. Authentication is triggered by the supported device connection flow when the SDK determines it is needed.

Observe the Terminal Result​

Implement the SDK or device delegate callback:

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

The callback is the host app's terminal signal. Sending bridge data successfully is only transport progress, not authentication success.

Ordering and Retry​

For devices that also require another AI authentication bridge, the SDK may sequence on-device voice assistant authentication after that earlier result. Do not start a competing authentication attempt from UI code.

The current public contract does not define a manual retry API, timeout, persisted authentication lifetime, or a complete error-code recovery table. On failure, preserve the error for diagnostics, keep assistant modes unavailable when product policy requires authentication, and let a documented reconnect or future SDK retry contract control the next attempt.

Security Boundary​

  • Treat bridge data as opaque credential material.
  • Never log payload bytes, device identity, or derived secrets in production.
  • Do not cache or replay bridge packets.
  • Keep the plugin and its encryption dependency at matching SDK versions.
  • Surface only user-actionable failure state; retain detailed errors in protected diagnostics.

Validation Checklist​

  • The bridge plugin is registered before device connection.
  • All-in-One and modular registration are not mixed.
  • UI waits for the final delegate callback.
  • Bridge packets are neither parsed nor persisted by the host app.
  • Failure does not silently enable an assistant mode that requires authentication.
  • Disconnect and reconnect behavior is tested on each supported device family.