メインコンテンツまでスキップ

ベストプラクティス

AIBuds の機能は、Bluetooth コマンド、デバイスが提供する Wi-Fi を使うワークフロー、AI サービス、メディア処理、任意の診断モジュールにまたがります。信頼性の高い統合では、SDK の各呼び出しを個別の要求として扱うのではなく、これらの境界を明確にします。

モジュールの境界を明確にする​

  • AIBudsFoundation には、共有モデル、Capability、値型が含まれます。
  • AIBuds は、デバイスの検出、接続、デバイス向け機能プロトコルを管理します。
  • AI モジュールは、サービスプロバイダーの設定と AI セッションのライフサイクルを管理します。
  • Logging、AI Dashboard、Live Streaming、Crash Reporter、Video Stabilization は、任意で導入する運用またはメディア用モジュールです。
  • SDK 一式を意図的に採用する製品には AIBudsAllInOne が適しています。モジュール別に構成する製品では、使用するものだけを統合してください。

製品方針は SDK レイヤーの外側に置きます。UI コントローラーはコーディネーターに処理を依頼し、そのオーナーが完了まで接続中のデバイス、コールバック、プレーヤー、インポーター、AI セッションを保持します。

SDK のオーナーを 1 つにする​

選択したモジュールはアプリのライフサイクル中に 1 回だけ初期化し、設定、デリゲート、プロバイダー選択、任意プラグインの登録を 1 か所にまとめます。初期化の正しい手順は設定を基準とし、機能ページごとに別の初期化経路を作らないでください。

準備状態と対応機能を確認する​

接続済みのデバイスが、すべての機能を実装しているとは限りません。操作を呼び出す前に、次の点を確認します。

  1. 対象のデバイスが引き続きアクティブで、使用可能な状態であること。
  2. DeviceInfoAPI や LiveStreamingAPI など、機能プロトコルに準拠していること。
  3. 機能固有の Capability プロパティがある場合は、その値を確認すること。
  4. コマンドの失敗によって対応状況を判定するのではなく、利用不可の状態を UI に表示すること。

再接続またはデバイス切り替え後は、これらの条件を改めて確認します。Capability をアカウント全体の製品設定としてキャッシュしないでください。

受付と完了を区別する​

多くのコールバックは、一連の処理における 1 つの段階を通知します。OTA の開始、デバイスモードへの移行、RTSP アドレスの受信、メディアのダウンロード完了は、それぞれ異なるマイルストーンです。

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

最終結果は、ドキュメントに記載された終端コールバックだけで判断します。開始コールバックの成功、進捗 100%、途中で得られた URL を、処理全体の成功として表示してはいけません。特に OTA、Camera OTA、Media File Import、Live Streaming、AI 録音、同時通訳、明示的な開始／停止を持つ機能で重要です。

クリーンアップを冪等にする​

長時間実行される各ワークフローには、1 つのオーナーと 1 つのクリーンアップ経路を設けます。成功、失敗、キャンセル、画面遷移、切断、バックグラウンド移行のどの後でも安全に実行できるようにしてください。一般的なクリーンアップには次が含まれます。

  • 対応している場合はデバイス側セッションを停止する。
  • ローカルのプレーヤー、ストリーマー、レコーダー、プロセッサーを停止して解放する。
  • 購読をキャンセルし、オブザーバーを解除する。
  • 保留中の UI 処理を無効にする。
  • コールバックと一時ファイルを消去する。
  • 最終結果に基づいて UI を復元する。

画面が閉じたことを、ミドルウェアやデバイス処理が停止したことの根拠にしないでください。

コールバックキューは未指定として扱う​

API がキューを明示的に保証していない限り、UIKit の更新はメインキューにディスパッチし、デコード、ファイル I/O、解析など負荷の高い処理は別のキューで実行します。別の SDK コールバックを同期的に待って、SDK コールバックをブロックしないでください。

ネットワーク切り替えを考慮する​

Media File Import、Camera OTA、RTSP Live Streaming では、デバイスのホットスポットに接続する場合があります。iPhone のインターネット経路が変わる可能性があり、ホットスポットの切断は Bluetooth の状態とは独立しています。現在の段階を表示し、最初に発生した対処可能なエラーを保持して、ドキュメントで安全とされる境界からのみ再開してください。

機密データを慎重に扱う​

AI の文字起こし、録音、翻訳、レポート、ログ、クラッシュレポート、メディア、ダッシュボード画面には、ユーザーデータが含まれる可能性があります。

  • 保存と削除の方針を定義する。
  • 診断ツールを対象のビルドとネットワークだけに制限する。
  • ログから認証情報と識別子を除外する。
  • 有効にした機能で必要な権限だけを要求する。
  • アップロードと外部 AI 処理を製品のプライバシー設計に明示する。
  • SDK の一時出力を意図せず長期保存しない。

正式な出力とフォールバックを保持する​

ワークフローが元データと処理済みデータを生成する場合、派生データを検証するまで元データを保持します。たとえば、動画の手ぶれ補正に失敗しても、ダウンロード済みの元ファイルが無効になるとは限りません。

公開されている結果モデルと終端コールバックを正式な状態として扱います。Demo のラベル、推測したステータスコード、UI の進捗は表示上の情報であり、SDK の契約に代わるものではありません。

統合レビューのチェックリスト​

  • 初期化と任意プラグインの登録を 1 つのオーナーが管理している。
  • 各機能で準備状態、プロトコル準拠、Capability を確認している。
  • 中間コールバックと最終結果を区別している。
  • UIKit の変更をメインキューで実行している。
  • 長時間実行されるワークフローに冪等なクリーンアップがある。
  • ホットスポットとインターネット経路の変化を UX に反映している。
  • 任意処理に失敗しても元のメディアを保持している。
  • 診断データが製品のプライバシー方針に従っている。
  • 実機テストで中断、切断、再試行、画面遷移を確認している。
  • SDK の更新ごとに API Reference と機能ガイドを再確認している。