label-capture-cordova

Label Capture Cordova スキル

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

学習データに含まれる Scandit Label Capture API は古いか、誤っている可能性があります。Cordova プラグインの API（グローバルな Scandit.* 名前空間、deviceready による制御、プラグインのインストール、プラットフォームの準備）は、Web、React Native、Flutter、Capacitor の SDK とは異なります。

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

Cordova 固有の注意点：

• Scandit のコードはすべて deviceready の後に実行する必要があります。 それまではグローバルな Scandit.* 名前空間が設定されません。初期化処理は document.addEventListener('deviceready', () => {...}, false); で囲んでください。
• Cordova ではリスナーメソッド名に iOS 形式を使用します。 Validation Flow リスナーでは didCaptureLabelWithFields(fields) と didSubmitManualInputForField(field, oldValue, newValue) を使用します。Web での相当するメソッド onValidationFlowLabelCaptured／onManualInput は使用しません。
• フィールド API はクラスベースで、RN／Capacitor と同じ形式です（Flutter とは異なります）。 Scandit.CustomBarcode.initWithNameAndSymbologies(name, [...])、new Scandit.ExpiryDateText(name)、field.optional = false、Scandit.LabelCaptureSettings.settingsFromLabelDefinitions([...], {}) を使用してください。LabelCaptureSettingsBuilder／LabelDefinitionBuilder はなく、v8.5 のファクトリー関数による簡略記法もありません。これらは Web 専用です。
• cordova plugin add の実行後、またはバージョンを更新した後は、ネイティブ依存関係を同期するために cordova prepare ios（および cordova prepare android）を実行してください。iOS ではさらに、platforms/ios/ 内で新たに pod install を実行する必要があります。
• カメラの権限：iOS では、アプリの Info.plist（または config.xml 内の <config-file>）に NSCameraUsageDescription が必要です。Android では、CAMERA 権限はプラグインによって自動的に宣言されますが、minSdkVersion が API 23 以降を対象とする場合、実行時にリクエストする必要があります。
• Scandit.DataCaptureContext.initialize(licenseKey) はシングルトンのコンテキストを返します。コンテキストを複数作成しないでください。

製品に関するガイダンス

ユーザーが API に関する質問ではなく、設計上の判断を行っている場合は、必ず以下のルールを適用してください。これらは、Scandit が Label Capture の統合方法として推奨する内容を反映しています。

• デフォルトでは Validation Flow を使用してください。 新しい統合では、LabelCaptureBasicOverlay ではなく LabelCaptureValidationFlowOverlay を使用してください。ライブ AR オーバーレイや、Validation Flow の固定レイアウトでは実現できない UI が顧客に明示的に必要な場合に限り、Basic／Advanced オーバーレイの方法を推奨してください。references/validation-flow.md を参照してください。
• Validation Flow は全画面で表示する必要があります。 カード、ハーフシート、モーダルの一部、または高さが部分的なウィジェット内に配置しないでください。レイアウトでは、フィールドチェックリスト、手動入力シート、キーボードに全画面の高さが必要です。
• まず既製のラベルを試し、次に既製のフィールドを試してから、カスタムにしてください。 次の順序で確認します。（1）既製のラベル定義でユースケースに対応できますか？ — Scandit.LabelDefinition.createVinLabelDefinition(name)、Scandit.LabelDefinition.createPriceCaptureDefinition(name)、Scandit.LabelDefinition.createSevenSegmentDisplayLabelDefinition(name)。（2）既製のフィールドでラベルを構成できますか？ — ExpiryDateText、PackingDateText、DateText、WeightText、UnitPriceText、TotalPriceText、SerialNumberBarcode、PartNumberBarcode、ImeiOneBarcode、ImeiTwoBarcode。（3）最後の手段としてのみ、CustomText／CustomBarcode を使用してください。
• 新規開発の統合では、サンプルアプリを起点にしてください。 ユーザーが最初から作成する場合は、LabelCaptureSimpleSample（References テーブルのリンク）をクローンして、必要に応じて変更するよう推奨してください。
• 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 が存在するか、または呼び出し方が不明な場合、あるいは実行時エラーが発生した場合は、回答する前に該当するリファレンスページを取得してください。ユーザーに自分でドキュメントを確認するよう伝えてはいけません。回答後は、ユーザーがさらに確認できるよう、必ず関連リンクを記載してください。

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

1. まず、すでに取得したページ（例：Advanced Configurations ページ）に、そのページへの直接リンクがあるか確認してください。
2. 直接リンクが見つからない場合は、API インデックスを取得し（以下の表のFull API referenceを参照）、実際のリンクを抽出して、そのページを開いてください。

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

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

このスキルの例は、Cordova テンプレートおよび公式の LabelCaptureSimpleSample で標準となっている**プレーンな JavaScript（ES6 以降）**で記述されています。対象プロジェクトで TypeScript（Cordova プロジェクトの一部では使用されています）が使われている場合は、同じインポートと構造を保ち、必要に応じて型注釈を追加してください。グローバルな Scandit.* のアクセスパターンを変更したり、ES モジュールのインポートに切り替えたり、バンドラーの機能を前提にしたりしないでください。

ライセンスキー

スキャンには 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 を取得し、その ID を指定して get_license_key を呼び出してください。list_license_keys でキーがトライアルではないと分かった場合は、取得する前にユーザーに確認してください。チャットにはマスクされたプレビューのみを表示し、キー全体を決して出力しないでください。

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

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

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

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

リファレンス

トピック	リソース
Cordova の統合	はじめに · サンプル（LabelCaptureSimpleSample）
ラベル定義（フィールド、正規表現、プリセット）	ラベル定義
高度なトピック（検証フローのカスタマイズ、適応型認識、カスタムオーバーレイ）	高度な設定
API リファレンス全体	Label Capture API