label-capture-flutter

Label Capture Flutter スキル

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

学習データには、古い、または誤った Scandit Label Capture API が含まれている可能性があります。Flutter プラグインの API（パッケージ名、ビルダー API、プラグインの初期化、ウィジェットのライフサイクル）は、Web、React Native、Cordova、Capacitor の SDK とは異なります。

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

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

• Scandit API を呼び出す前に、プラグインを初期化する必要があります。 DataCaptureContext.initialize(licenseKey); を呼び出す前に、await ScanditFlutterDataCaptureLabel.initialize();（および await ScanditFlutterDataCaptureBarcode.initialize();）を呼び出してください。プラグインの initialize() を省略すると、実行時に原因のわかりにくい MethodChannel エラーが発生します。
• Flutter ではリスナーのメソッド名に iOS 形式を使用します。 Validation Flow では、didCaptureLabelWithFields(fields)、didSubmitManualInputForField(field, oldValue, newValue)、didUpdateValidationFlowResult(...) を使用します。Web での名前（onValidationFlowLabelCaptured、onManualInput）は Flutter には存在しません。
• リスナーインターフェースは 2 種類あります。 LabelCaptureValidationFlowListener が宣言するのは didCaptureLabelWithFields のみです。手動入力の送信やフレームごとの結果更新を処理するには、didSubmitManualInputForField と didUpdateValidationFlowResult を追加した基本リスナーの拡張である LabelCaptureValidationFlowExtendedListener を実装してください。
• Flutter のビルダー API。 フィールド定義にはビルダーを使用します：CustomBarcodeBuilder().setSymbologies([...]).isOptional(false).build(name)、LabelDefinitionBuilder().addCustomBarcode(...).addExpiryDateText(...).build(name)、LabelCaptureSettings([labelDefinition])。RN／Cordova／Capacitor（クラスベース）とは反対の方式です。混同しないでください。
• iOS（ios/Runner/Info.plist の NSCameraUsageDescription）と Android（自動的に宣言されます）の両方でカメラの権限が必要です。Android では permission_handler パッケージを使って実行時に権限をリクエストしてください。
• DataCaptureView は Flutter ウィジェットであり、そのライフサイクルはウィジェットツリーに連動します。WidgetsBindingObserver を介して didChangeAppLifecycleState でカメラを一時停止し、State の dispose() でリスナーを破棄してください。

製品に関するガイダンス

ユーザーが API に関する質問だけでなく、設計上の判断を行う際は、常に以下のルールを適用してください。これらは、Scandit が Label Capture の統合に推奨する方法を示しています。

• Validation Flow をデフォルトとして使用してください。 新しい統合では、LabelCaptureBasicOverlay ではなく LabelCaptureValidationFlowOverlay を使用してください。ライブ AR オーバーレイ、または Validation Flow の固定レイアウトでは実現できない UI を顧客が明示的に必要としている場合に限り、基本／高度なオーバーレイの方法を推奨してください。references/validation-flow.md を参照してください。
• Validation Flow は全画面で表示する必要があります。 カード、ハーフシート、モーダルの一部、または高さが限られたウィジェット内に配置しないでください。レイアウトは、フィールドチェックリスト、手動入力シート、キーボードに全画面の高さがあることを前提としています。
• まず既成ラベル、次に既成フィールド、それからカスタムを優先してください。 次の順序で試してください。（1）ユースケースをカバーする既成のラベル定義があるか — LabelDefinition.vinLabelDefinitionWithName(name)、LabelDefinition.priceCaptureDefinitionWithName(name)、LabelDefinition.sevenSegmentDisplayLabelDefinitionWithName(name)。（2）既成フィールドを使ってラベルを構成できるか — ExpiryDateText、PackingDateText、DateText、WeightText、UnitPriceText、TotalPriceText、SerialNumberBarcode、PartNumberBarcode、ImeiOneBarcode、ImeiTwoBarcode。（3）最後の手段としてのみ、CustomText／CustomBarcode を使用してください。
• 新規開発の統合では、サンプルアプリから始めてください。 ユーザーがゼロから開発を始める場合は、LabelCaptureSimpleSample（リンクは「参考資料」表を参照）をクローンして、必要に応じて変更するよう推奨してください。
• Label Capture 以外に関する質問は data-capture-sdk スキルに引き継いでください。 ユーザーが別の Scandit 製品（Barcode Capture、SparkScan、MatrixScan、ID Capture など）について、または製品の選択について質問した場合は、推測せずに data-capture-sdk スキルに引き継いでください。

インテントの振り分け

ユーザーの依頼に応じて、回答する前に適切な参考ファイルを読み込んでください。

• Label Capture をゼロから統合する（例：「アプリに Label Capture を追加する」「バーコードと賞味期限を含む値札をスキャンする」「Smart Label Capture の使い方」）→ references/integration.md を読んでください。デフォルトでは Validation Flow を統合します（統合ガイドでは Validation Flow を最初に取り上げています）。
• Validation Flow に関する質問（「カスタマイズするには」「何を変更できるか」「なぜこのように実装されているのか」「手動編集にどう対応するか」「色を変更できるか」）→ references/validation-flow.md を読んでください。
• Validation Flow を超える視覚的なカスタマイズ（「ライブ AR オーバーレイ」「読み取ったフィールドごとにタグを描画する」「スキャン中にカメラフレームを取得する」）→ references/customization.md を読んでください。
• Adaptive Recognition Engine／クラウドへのフォールバック／レシートのスキャン（「ARE を有効にするには」「クラウド認識を使用する」「レシートをスキャンする」「AdaptiveRecognitionMode」「ARE は本番環境で利用できるか」）→ references/adaptive-recognition.md を読んでください。
• 既存の Label Capture 統合の移行またはアップグレード → references/migration.md を読んでください。

API 使用ポリシー

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

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

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

URL の構造は SDK のバージョンやパッケージのパスによって異なり、推測すると 404 エラーになります。

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

このスキルの例では、公式の LabelCaptureSimpleSample とその他の Flutter Scandit サンプルで使用されている StatefulWidget + WidgetsBindingObserver を使います。対象のプロジェクトで状態管理ライブラリ（BLoC、Riverpod、Provider）を使用している場合は、同じプラグイン初期化コードとフィールド／ビルダーのコードを維持したまま、リスナーとライフサイクルをそのパターンに組み込んでください。Label Capture のためだけに新しい状態管理ライブラリを導入しないでください。

例は Dart（健全な null 安全性）で記述されています。Flutter >=3.10 と Dart >=3.0 が必要です。

ライセンスキー

スキャンには 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 との統合	はじめに · サンプル（LabelCaptureSimpleSample）
ラベル定義（フィールド、正規表現、プリセット）	ラベル定義
高度なトピック（検証フローのカスタマイズ、適応型認識、カスタムオーバーレイ）	高度な設定
API リファレンスの全内容	ラベルキャプチャ API