barcode-capture-flutter

BarcodeCapture Flutter スキル

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

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

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

注意すべき Flutter 固有のポイント：

• await ScanditFlutterDataCaptureBarcode.initialize() は、WidgetsFlutterBinding.ensureInitialized() の後、runApp(...) の前に main() で呼び出し、完了を待つ必要があります。これを忘れると、初期化とは無関係に見えるプラットフォームチャネルエラーが発生します。
• DataCaptureContext は 1 つだけ作成し、そのコンテキストで BarcodeCapture モードと DataCaptureView の両方を管理する必要があります。ページごと、または MaterialApp ごとに複数のコンテキストを作成しないでください。コンテキストを保持する BLoC／コントローラーは、個々の State より長く存続する必要があります。
• DataCaptureView は DataCaptureView.forContext(context) が返す Flutter の Widget です。view.addOverlay(...) を使って、BarcodeCaptureOverlay を明示的に追加する必要があります。SparkScan とは異なり、あらかじめ用意されたスキャン UI はありません。カメラプレビュー上に認識したバーコードを表示するのは、このオーバーレイだけです。
• BarcodeCaptureListener.didScan(...) は、戻るまで認識パイプラインをブロックします。コールバック内で実質的な処理を行う前にモードを無効化（barcodeCapture.isEnabled = false）し、処理が終わったら再び有効にするか、カメラを停止してください。そうしないと、重複したスキャンイベントや不要なスキャンイベントが発生します。
• Flutter リスナーの getFrameData パラメーターは Future<FrameData?> Function() です。フレームデータは遅延取得されます。プラットフォームチャネルを介するため、本当に必要な場合にのみ呼び出してください。
• パッケージのバージョンを変更するたびに、flutter pub get を実行する必要があります。iOS では Podfile が依存関係を推移的に解決するため、カスタム設定でない限り手動での pod install は不要です。
• iOS（ios/Runner/Info.plist の NSCameraUsageDescription）と Android（permission_handler を介した実行時のリクエスト）の両方でカメラの権限が必要です。プラグインがマニフェストの権限を自動的に宣言します。
• ホットリロードでは main() は再実行されないため、カメラのライフサイクルと ScanditFlutterDataCaptureBarcode.initialize() の呼び出しはホットリロード後も維持されます。プラグインの初期化を再実行するには、完全に再起動する必要があります。WidgetsBindingObserver.didChangeAppLifecycleState から camera.switchToDesiredState(...) を呼び出し、paused でカメラを停止し、resumed で再開してください。

インテントの振り分け

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

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

API 使用ポリシー

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

コードの作成または移行後は、dart analyze（または flutter analyze）を実行し、回答する前にすべてのエラーと警告を修正してください。

ドキュメントの URL を決して作り上げたり、推測したりしてはいけません。 特定のクラスやプロパティの API ページが必要な場合は、次の手順に従ってください。

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

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

フレームワークのバリエーションに関するポリシー

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

ライセンスキー

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

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

1. Scandit MCP サーバーが接続されている場合 — 製品に native、プラットフォームに ios と android、app_identifier（アプリのバンドル ID またはアプリケーション ID。Web の場合は本番ドメインで、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 との統合	はじめに · サンプル
高度なトピック（カスタムフィードバック、ビューファインダー、位置の選択、スキャン意図、複合コード）	高度な設定
SDK のメジャーバージョン間の移行	6 → 7 · 7 → 8
API リファレンス全体	BarcodeCapture API