Skip to main content

Best Practices

AIBuds features span Bluetooth commands, device-hosted Wi-Fi workflows, AI services, media processing, and optional diagnostic modules. A reliable integration makes those boundaries visible instead of treating every SDK call as an isolated request.

Keep Module Boundaries Explicit​

  • AIBudsFoundation contains shared models, capabilities, and value types.
  • AIBuds owns device discovery, connection, and device-facing feature protocols.
  • AI modules own provider configuration and AI session lifecycles.
  • Logging, AI Dashboard, Live Streaming, Crash Reporter, and Video Stabilization are optional operational or media modules.
  • AIBudsAllInOne is appropriate when the product intentionally adopts the complete suite; modular products should integrate only what they use.

Keep product policy outside the SDK layer. UI controllers should ask a coordinator to perform work, while that owner retains the active device, callbacks, player, importer, or AI session until completion.

Establish One SDK Owner​

Initialize selected modules once during the application lifecycle and keep configuration, delegates, provider selection, and optional plugin registration in one place. Use Configuration as the initialization source of truth; feature pages should not become alternate initialization paths.

Check Readiness and Capability​

A connected device does not necessarily implement every feature. Before invoking an operation:

  1. Confirm that the intended device is still active and ready.
  2. Check conformance to the feature protocol, such as DeviceInfoAPI or LiveStreamingAPI.
  3. Check the feature-specific capability property when one exists.
  4. Show an unavailable state instead of using command failure as capability detection.

Re-evaluate these conditions after reconnecting or switching devices. Do not cache capabilities as account-wide product settings.

Separate Acceptance from Completion​

Many callbacks report one stage of a larger operation. Starting OTA, entering a device mode, receiving an RTSP address, and finishing a media download are different milestones.

TEXT
idle -> preparing -> active/progress -> finishing -> completed | failed | cancelled

Only the documented terminal callback should decide the final result. A successful start callback, progress of 100%, or an intermediate URL must not be presented as end-to-end success. This matters most for OTA, Camera OTA, Media File Import, Live Streaming, AI recording, simultaneous interpretation, and explicit start/stop features.

Make Cleanup Idempotent​

Give each long-running workflow one owner and one cleanup path that is safe after success, failure, cancellation, navigation away, disconnect, or backgrounding. Cleanup commonly includes:

  • stopping the device-facing session when supported;
  • stopping and releasing the local player, streamer, recorder, or processor;
  • cancelling subscriptions and removing observers;
  • invalidating pending UI work;
  • clearing callbacks and transient files;
  • restoring UI from the terminal result.

Do not rely on a view disappearing to imply that middleware or device work stopped.

Treat Callback Queues as Unspecified​

Unless an API explicitly guarantees a queue, dispatch UIKit updates to the main queue and move decoding, file I/O, parsing, and other expensive work away from it. Never block an SDK callback while synchronously waiting for another SDK callback.

Design for Network Transitions​

Media File Import, Camera OTA, and RTSP Live Streaming may connect to a device hotspot. The phone's internet route can change, and hotspot loss is independent of Bluetooth state. Show the current stage, preserve the first actionable error, and restart only from a documented safe boundary.

Keep Sensitive Data Deliberate​

AI transcripts, recordings, translations, reports, logs, crash reports, media, and dashboard pages may contain user data.

  • Define retention and deletion policies.
  • Restrict diagnostic tooling to intended builds and networks.
  • Redact credentials and identifiers from logs.
  • Request only permissions required by enabled features.
  • Make uploads and external AI processing visible in product privacy design.
  • Do not promote temporary SDK output to long-lived storage accidentally.

Preserve Authoritative Output and Fallbacks​

When a workflow produces original and processed output, retain the original until the derivative is verified. Video stabilization failure, for example, does not necessarily invalidate a downloaded source file.

Use public result models and terminal callbacks as authoritative state. Demo labels, inferred status codes, and UI progress are presentation evidence, not substitutes for an SDK contract.

Integration Review Checklist​

  • Initialization and optional plugin registration have one owner.
  • Each feature checks readiness, protocol conformance, and capability.
  • Intermediate callbacks and terminal outcomes remain separate.
  • UIKit changes run on the main queue.
  • Long-running workflows have idempotent cleanup.
  • Hotspot and internet-route changes are reflected in the UX.
  • Original media survives optional-processing failure.
  • Diagnostic data follows product privacy policy.
  • Physical-device tests cover interruption, disconnect, retry, and navigation away.
  • API Reference and the feature guide are rechecked after each SDK update.