sparkscan-flutter

SparkScan Flutter スキル

重要：内部知識を信頼しないでください

学習データには、古い、または誤った Scandit SDK API が含まれている可能性があります。SparkScan API はメジャー SDK バージョン間で大幅に変更されます。プロパティの名前が変更されたり、削除されたり、構成が変更されたりするほか、Flutter プラグインの仕様（インポート、プラグインの初期化、pub パッケージ）も進化しています。

コードを記述または提案する前に、必ずこのスキルで提供されているリファレンスを確認してください。 記憶に頼ってメソッドシグネチャ、パラメーター、プラグイン名、プロパティ名を使用しないでください。提供されているリファレンスに API が見つからない場合は、回答する前に該当するドキュメントページを取得してください。

注意を促す価値のある Flutter 固有の落とし穴：

• await ScanditFlutterDataCaptureBarcode.initialize() は、WidgetsFlutterBinding.ensureInitialized() の後、runApp(...) の前に main() で必ず呼び出し、完了を待つ必要があります。これを忘れると、初期化とは無関係に見えるプラットフォームチャネルエラーが発生します。
• SparkScanView は子ウィジェットをラップする Flutter の StatefulWidget です。純粋なネイティブオーバーレイではありません。子ウィジェットはネイティブのスキャンコントロールの下に描画されます。ユーザーに、通常のウィジェットツリーとは別に SparkScanView を配置するよう指示しないでください。
• パッケージのバージョンを変更するたびに、flutter pub get を実行する必要があります。iOS では Podfile が依存関係を推移的に解決するため、ユーザーが独自の設定を使用している場合を除き、手動での pod install は不要です。
• カメラの権限は iOS（ios/Runner/Info.plist の NSCameraUsageDescription）と Android（permission_handler による実行時のリクエスト）の両方で必要です。プラグインによってマニフェスト権限は自動的に宣言されます。

意図の振り分け

ユーザーのリクエストに基づいて、回答する前に適切なリファレンスファイルを読み込んでください。

• SparkScan を新規に統合する（例：「アプリに SparkScan を追加したい」「バーコードスキャンを設定したい」「Flutter で SparkScan を使う方法は？」「SparkScan でフィードバックを処理する方法は？」）→ references/integration.md を読み、そこに記載された手順に従ってください。
• 既存の SparkScan 統合を移行またはアップグレードする（例：「v6 から v7 にアップグレードしたい」「SparkScan を移行したい」「Scandit パッケージを v8 に上げたい」「SDK バージョン間で何が変わった？」）→ references/migration.md を読み、そこに記載された手順に従ってください。
• サードパーティ製スキャナーを SparkScan に置き換える（例：「mobile_scanner から移行したい」「google_mlkit_barcode_scanning を Scandit に置き換えたい」「既存のバーコードプラグインを SparkScan に差し替えたい」）→ references/third-party-migration.md を読み、そこに記載された手順に従ってください。

API の使用方針

以下の Scandit リファレンスに明示的に記載されている API のみを使用してください。メソッドシグネチャ、パラメーター、プロパティ名、インポートを捏造したり、推測したりしないでください。API が存在するか、または呼び出し方法が不明な場合、あるいはアナライザー／実行時エラーが発生した場合は、回答する前に該当するリファレンスページを取得してください。ユーザー自身でドキュメントを確認するよう伝えないでください。回答後は、ユーザーがさらに詳しく確認できるよう、必ず関連リンクを含めてください。

ドキュメント URL を組み立てたり、推測したりしないでください。 特定のクラスまたはプロパティの API ページが必要な場合：

1. まず、すでに取得したページ（例：Advanced Configurations ページ）に、そのページへの直接リンクが含まれているか確認してください。トピックページには関連する API シンボルへの直接リンクがあります。取得を依頼するときは、コンテンツとあわせてリンクも含めるよう、必ず指定してください。
2. 直接リンクが見つからない場合は、API インデックスを取得し（下の表の完全な API リファレンスを参照）、そこから実際のリンクを抽出してアクセスしてください。

URL の構造は SDK バージョンやパッケージのパスによって異なります（例：api/ui/ サブディレクトリ）。推測すると 404 エラーになります。

フレームワークの方針

Flutter アプリでは、さまざまな状態管理パターン（StatefulWidget、BLoC、Provider、Riverpod）が使われています。このスキルの例では、公式の ListBuildingSample と一致し、スキャンパイプラインをウィジェットツリーから明確に分離でき、カメラのライフサイクルともうまく組み合わせられるため、BLoC パターンを使用します。対象のプロジェクトですでに別のパターン（Provider、Riverpod、GetX、通常の StatefulWidget）が使われている場合は、SparkScan の接続方法の考え方（DataCaptureContext と SparkScan を保持する単一の所有者が、スキャンイベントを UI に公開する）をそのままにし、コード例をプロジェクト既存の規約に合わせて移植してください。プロジェクトの状態管理を書き換えてはいけません。

ライセンスキー

スキャンには Scandit のライセンスキーが必要です。このスキルでは、ライセンス製品は native、ライセンスプラットフォームは ios と android です。

次の手順を順番に進めてください。MCP が原因でユーザーを待たせてはいけません。

1. Scandit MCP サーバーに接続されている場合 — 製品に native、プラットフォームに ios と android、app_identifier（アプリのバンドル ID またはアプリケーション ID。ウェブの場合は本番ドメインで、localhost は不可）、env_var に SCANDIT_LICENSE_KEY を指定して ensure_scanner_setup を呼び出します。返されたコマンドは実行しないでください。次に、その結果または list_license_keys から取得したキー ID を使って get_license_key を呼び出します。list_license_keys でキーがトライアルではないと示された場合は、取得する前にユーザーに確認してください。チャットに表示するのは、最大でもマスク済みのプレビューにしてください。キー全体を表示してはいけません。

2. 接続されていない場合 — ユーザーに、MCP クライアントでリモート Scandit MCP サーバー https://ssl.scandit.com/mcp に接続できることを一度だけ伝え、その後、手順 1 から続けてください。MCP クライアントの設定を自分で編集してはいけません。

   認証はブラウザーを使うため、ヘッドレス環境や CI ではサポートされていません。サーバーが発行するのはトライアルキーのみです。本番ライセンスの作成、失効、変更は行いません。

3. ユーザーが希望しない場合、または MCP クライアントを持っていない場合 — ユーザー自身で https://ssl.scandit.com からキーを生成してもらい（アカウントがない場合は https://ssl.scandit.com/dashboard/sign-up?p=test）、キーを貼り付けてもらってください。

次に、キーをコードに設定します：プレースホルダーの代わりに、ライセンスキー呼び出しへキーを書き込んでください。キーは、get_license_key が返したもの、またはユーザーが貼り付けたものや伝えたものを使用します。チャットには引き続き、マスク済みのプレビューのみを表示してください。キーを探すために、プロジェクト、そのファイル、または環境を検索してはいけません。

参考資料

ユーザーの質問に応じて、適切なリソースを案内してください。

トピック	リソース
Flutter の統合	はじめに · サンプル
高度なトピック（カスタムフィードバック、ハードウェアトリガー、スキャンモード、UI のカスタマイズ）	高度な設定
SDK のメジャーバージョン間の移行	6 → 7 · 7 → 8
API リファレンス全体	SparkScan API