plaud-embedded-ios-sdk-skill

Plaud Embedded iOS SDK スキル

このスキルでは、Plaud Embedded iOS SDK の実装に関するコンテキストと手順を提供します。

このスキルを使用するタイミング

ユーザーがネイティブ iOS アプリを Plaud の録音デバイス（Plaud NotePin S および Plaud Note Pro）に接続したい場合に、このスキルを使用します。

このスキルを使い始める前に、ユーザーが次の前提条件を満たしていることを確認してください。

前提条件

• Plaud Developer Portal から Plaud Embedded の認証情報（CLIENT_ID、CLIENT_SECRET、API_KEY）をすでに取得している
• Plaud の Authentication API を通じて User Token を取得する手段がある

ユーザーがこれらの前提条件を両方とも満たしていない場合は、手順について plaud-embedded-project-setup-skill を使用してください。

はじめに

インストールガイドの手順に従ってください。

互換性要件

要件	値
iOS のデプロイメントターゲット	14.0+
Xcode	16.0+（SDK は Swift 6.0.3 でビルドされています）
アーキテクチャ	arm64 実機のみ — iOS シミュレーターはサポートされていません

SDK はビルド済みフレームワークとして提供され、sdk/ios/ の plaud-sdk-public からクローンされます。

フレームワーク	Xcode での操作
PlaudBleSDK.framework	Embed & Sign
PlaudWiFiSDK.framework	Embed & Sign
PlaudDeviceBasicSDK.framework	Embed & Sign
PlaudDeviceBasicSDK.bundle	Copy Bundle Resources

ご注意ください。iOS 用 Embedded SDK に必要なエンタイトルメントのうち、WiFi Fast Transfer には Hotspot Configuration エンタイトルメントが必要です。バンドル、フレームワーク、エンタイトルメントの追加方法については、サンプルの Xcode 設定を参照してください。

統合方法を選択する

Embedded SDK はネイティブ iOS SDKですが、ユーザーのスタックに応じて複数の利用方法があります。

ユーザーのスタック	方法	参照先
既存のアプリがない	Plaud の iOS Starter App をデプロイする	以下の「Plaud Starter App のデプロイ方法」
既存のネイティブ iOS アプリがある	SDK を直接実装する	以下の「iOS 用 Embedded SDK の実装方法」
React Native アプリ	Plaud の Expo Native Module	React Native のドキュメント · embedded-react-native
Flutter アプリ	Plaud の plaud_sdk Flutter プラグイン	Flutter のドキュメント · embedded-flutter
Web アプリ	Plaud の Capacitor プラグインでネイティブ iOS アプリにラップする	Web アプリラッパーのドキュメント · embedded-capacitor

React Native、Flutter、Capacitor のプラグインでは、基本機能（デバイス接続、ファイル同期、文字起こし）が実装されています。WiFi Fast Transfer などの高度な用途には、プラグインにメソッドを追加するか、ネイティブ iOS SDK を直接使用してください。

Plaud Starter App のデプロイ方法

Plaud Starter App は、Embedded SDK がすでに実装された、完成済みの iOS アプリです。

Starter App には、ユーザーがすぐに利用できる多数の実装済み機能が含まれています。

ユーザーに Starter App のリポジトリをクローンし、Starter App ガイドの手順に従うよう案内してください。

重要：PlaudTemplateApp.xcodeproj はソース管理されておらず、project.yml から生成されます。プロジェクトを開く前に、ユーザーは XcodeGen（brew install xcodegen）をインストールし、xcodegen generate を実行する必要があります。また、project.yml を編集した後は、再度実行してください。

認証情報は PartnerConfig.xcconfig（USER_ACCESS_TOKEN、PLAUD_CLIENT_ID、PLAUD_API_KEY）に設定します。ローカル開発では、プレースホルダーを上書きする、Git の追跡対象外となる PartnerConfig.local.xcconfig をその隣に作成してください。

iOS 向け Embedded SDK の実装方法

Embedded SDK は、次の機能を提供する iOS ライブラリです。

1. Plaud デバイスをユーザーの iOS モバイルアプリに接続（バインド）し、バインドを解除します
2. Plaud デバイスからユーザーのモバイルアプリに音声を同期します。BLE または WiFi Fast Transfer（約 10 倍高速）を使用でき、すべての録音を一括ダウンロードできます
3. 音声を複数の形式（.pcm（0）、.mp3（1）、.wav（2）、.opus（3））でエクスポートします。.mp3 を推奨します。あらゆる環境で再生でき、文字起こしアップロード API でもそのまま受け付けられます
4. 接続済みの Plaud デバイスのファームウェアを無線（OTA）で更新します

高水準のファサードは 2 つあります。PlaudDeviceAgent（BLE のライフサイクル、ファイル同期、ファームウェア）と PlaudWiFiAgent（WiFi Fast Transfer）で、どちらも .shared シングルトンから利用できます。initSDK(userAccessToken:customDomain:) で一度だけ初期化してください。customDomain には、https:// 接頭辞を付けずに Plaud ドメインを指定します（例：platform-us.plaud.ai）。

SDK はデリゲート駆動型です。プロトコル（PlaudDeviceAgentProtocol、AudioExportCallback、PlaudWiFiAgentProtocol）を実装して、デバイスイベント、転送の進捗状況、結果を受け取ります。

重要：Plaud デバイスは一度に 1 つのアプリケーションにのみ バインドできます。アプリをアンインストールする前にデバイスのバインドを解除するよう ユーザーに伝えてください。バインドを解除しないと、デバイスを復旧するまで別のアプリ（または Plaud アプリ）にバインドできません。

注：デバイスのバインドと解除では、API を呼び出す前に、まず SDK のメソッドを使用してください。これにより、クラウドの状態がデバイスの実際の状態と一致します。デバイスのバインドまたは解除に失敗した場合は、API を呼び出さないでください。

SDK に含まれる主要なメソッドとプロトコルについては、iOS SDK のドキュメントを参照してください。

高水準ファサードで公開されていない動作については、iOS SDK の高度な使用方法に関するドキュメントを参照してください。低水準の BleAgent、WiFiAgent、PlaudPartnerApiManager について説明しています。高水準ファサードと低水準ファサードは組み合わせて使用できますが、高水準ファサードを主な制御手段として使用してください。低水準エージェントにはない、パートナーの事前ハンドシェイク、E2EE の復号、音声形式の変換、パラメーターの検証を処理します。

参考資料として、以下をご覧ください。

• SDK のヘッダーファイルを確認できる SDK リポジトリ
• iOS Embedded SDK が完全に実装された Plaud Starter App
• Starter App で特に参考になるファイル：
  • DeviceManager.swift
  • SyncManager.swift

完了の定義 - Embedded SDK の実装完了

ユーザーが次の操作を行えること：

• Plaud デバイスをモバイルアプリに接続する
• BLE または WiFi Fast Transfer で Plaud デバイスからアプリに音声ファイルを同期する
• クラウドと BLE の両方で、アプリから Plaud デバイスのバインドを解除する