matrixscan-ar-flutter

MatrixScan AR Flutter スキル

重要：内部知識を鵜呑みにしないでください

トレーニングデータに、古くなった、または誤った Scandit SDK API が含まれている可能性があります。BarcodeAr API は、メジャー SDK バージョン間で変更されます。クラス名、コンストラクターのシグネチャー、プロバイダーのインターフェース、Flutter プラグインのインポートパスはすべて進化してきました。

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

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

• await ScanditFlutterDataCaptureBarcode.initialize() は、runApp(...) の前に main() で（WidgetsFlutterBinding.ensureInitialized() の後に）呼び出して、完了を待つ必要があります。これを忘れると、初期化とは無関係に見えるプラットフォームチャネルエラーが発生します。
• BarcodeArView は Flutter の StatefulWidget です。initState() で一度だけ作成し（build() 内では作成しないでください）、フィールドに保存して、ウィジェットツリーに組み込んでください。build() 内で作成すると、再ビルドのたびにネイティブビューが破棄され、再作成されます。
• ハイライトとアノテーションのプロバイダー（BarcodeArHighlightProvider、BarcodeArAnnotationProvider）は、それぞれ Future<BarcodeArHighlight?> と Future<BarcodeArAnnotation?> を返します。これらのコールバックは非同期です。通常の値を返さないでください。
• BarcodeArCustomHighlight と BarcodeArCustomAnnotation は、スナップショットとしてシリアライズされる Flutter の Widget 子要素を使用します。アニメーション付きウィジェットは描画時に静止画としてキャプチャされ、AR オーバーレイ内ではアニメーションしません。
• BLoC（または同等のコントローラー）が DataCaptureContext、BarcodeAr、カメラのライフサイクルを管理します。State クラスは BarcodeArView を保持し、プロバイダーのインターフェースを実装します。
• iOS（ios/Runner/Info.plist の NSCameraUsageDescription）と Android（permission_handler による実行時のリクエスト）の両方でカメラ権限が必要です。プラグインによってマニフェストの権限は自動的に宣言されます。
• バーコード AR のインポートは scandit_flutter_datacapture_barcode_ar です。これは、メインの scandit_flutter_datacapture_barcode インポートとは別のバレルファイルです。
• Symbology の enum 値は、Dart では lowerCamelCase を使用します：Symbology.code128、Symbology.ean13Upca、Symbology.code39、Symbology.qr、Symbology.dataMatrix。Symbology.Code128 / Symbology.EAN13UPCA は記述しないでください。これは JS/TS の形式であり、Dart ではコンパイルできません。

インテントに基づく振り分け

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

• BarcodeAr をゼロから統合する（例：「アプリに MatrixScan AR を追加したい」、「バーコード AR スキャンを設定したい」、「Flutter で BarcodeAr を使うには」、「追跡中のバーコードにハイライトを表示するには」、「情報アノテーションを表示するには」）→ references/integration.md を読み、そこに記載された手順に従ってください。

• BarcodeBatch / BarcodeTracking から BarcodeAr に移行する（例：「BarcodeBatch から移行したい」、「BarcodeBatch を BarcodeAr に変換したい」、「MatrixScan から MatrixScan AR に移行したい」、「BarcodeTracking を BarcodeAr に置き換えたい」、「古い MatrixScan コードを AR 用にアップグレードしたい」）→ references/migration.md を読み、そこに記載された 10 段階の移行ガイドに従ってください。

API 使用ポリシー

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

ドキュメントの URL を作成したり、推測したりしてはいけません。 特定のクラスやプロパティの API ページが必要な場合：

1. まず、すでに取得したページに、そのページへの直接リンクがあるか確認してください。トピックページには、関連する API シンボルへの直接リンクがあります。
2. 直接リンクが見つからない場合は、API インデックス（以下の表の完全な API リファレンスを参照）を取得し、そこから実際のリンクを抽出して、そのリンク先を確認してください。

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

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

Flutter アプリでは、さまざまな状態管理パターン（StatefulWidget、BLoC、Provider、Riverpod）が使われています。このスキルの例では、公式の MatrixScanARSimpleSample に沿っており、スキャンパイプラインをウィジェットツリーから明確に分離でき、カメラのライフサイクルとも相性がよい BLoC パターンを使用します。対象プロジェクトがすでに別のパターン（Provider、Riverpod、GetX、標準の StatefulWidget）を使用している場合は、BarcodeAr の接続方法の考え方（1つのオーナーが DataCaptureContext と BarcodeAr を保持し、セッションデータを 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 の統合	はじめに · サンプル
完全な API リファレンス	BarcodeAr API