label-capture-capacitor

Label Capture Capacitor スキル

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

トレーニングデータには、古くなった Scandit Label Capture API や誤った Scandit Label Capture API が含まれている可能性があります。Capacitor プラグインの仕様（ES モジュールのインポート、initializePlugins()、webViewContentOnTop の切り替え）は、Web、React Native、Flutter、Cordova の SDK とは異なります。

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

Capacitor 固有の注意点：

• プラグインは最初に初期化する必要があります。 DataCaptureContext.initialize(licenseKey) の前に、await ScanditCaptureCorePlugin.initializePlugins(); を呼び出してください。この手順を省略すると、実行時にプラグインブリッジエラーが発生します。
• webViewContentOnTop の切り替え。 ネイティブのスキャンビューは WebView の背後に表示されます。スキャン中は view.webViewContentOnTop = false に設定して、ネイティブのオーバーレイ UI がタッチイベントを受け取れるようにしてください。結果モーダルなど、DOM ベースの UI を前面に表示する場合は、view.webViewContentOnTop = true に戻してください。この設定を忘れることが、「スキャン中にモーダルやボタンが動作しない」または「スキャン UI が見えない」という問題の最も一般的な原因です。
• リスナーメソッド名は Capacitor では iOS スタイルです。 Validation Flow リスナーでは、didCaptureLabelWithFields(fields)、didSubmitManualInputForField(field, oldValue, newValue)、didUpdateValidationFlowResult(...) を使用します。Web 用の名前（onValidationFlowLabelCaptured、onManualInput）は Capacitor にはありません。
• フィールド API はクラスベースです。 RN／Cordova と同じ形式で、Flutter とは異なります。CustomBarcode.initWithNameAndSymbologies(...)、new ExpiryDateText(...)、field.optional = false、LabelCaptureSettings.settingsFromLabelDefinitions([...], {}) を使用します。LabelCaptureSettingsBuilder／LabelDefinitionBuilder や、v8.5 のファクトリー関数による簡略記法はありません。これらは Web 専用です。
• Scandit パッケージのインストール後またはアップグレード後に、npx cap sync を実行してください（iOS の場合は cd ios/App && pod install も実行してください）。
• カメラの権限：iOS では ios/App/App/Info.plist に NSCameraUsageDescription が必要です。Android ではプラグインによって自動的に宣言されます。minSdkVersion >= 23 の場合は、@capacitor/camera または @capgo/permission を使って実行時に権限をリクエストしてください。

製品に関するガイダンス

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

• デフォルトでは Validation Flow を使用します。 新規の統合では、LabelCaptureBasicOverlay ではなく LabelCaptureValidationFlowOverlay を使用してください。Validation Flow の固定レイアウトでは実現できないライブ AR オーバーレイや UI が顧客から明示的に求められている場合に限り、基本／高度なオーバーレイの方法を推奨してください。references/validation-flow.md を参照してください。
• Validation Flow は全画面で表示する必要があります。 カード、ハーフシート、モーダルの一部、または高さが部分的なウィジェットの中に配置しないでください。フィールドチェックリスト、手動入力シート、キーボードのために、全画面の高さを前提としたレイアウトになっています。
• まず既成ラベル、次に既成フィールドを試し、最後にカスタム実装を検討してください。 次の順番で試してください。（1）既成のラベル定義でユースケースに対応できますか？ — LabelDefinition.createVinLabelDefinition(name)、LabelDefinition.createPriceCaptureDefinition(name)、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 をゼロから統合する → 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 インデックスを取得して、そこからリンクをたどってください。

フレームワークのバリアントに関する方針

このスキルの例では、ES モジュールインポートを使用したプレーンな JavaScriptを使います。これは、Capacitor テンプレートと公式のLabelCaptureSimpleSampleのデフォルトだからです。対象のプロジェクトがフレームワーク（React、Vue、Angular、Ionic）を使用している場合は、Scandit の初期化とセットアップをコンポーネントツリーの外側に置きます（たとえば、シングルトンコンテキストをエクスポートする小さなモジュールを作成します）。そのうえで、フレームワークのコンポーネントから呼び出してください。Label Capture のためだけに状態管理ライブラリを導入しないでください。

ライセンスキー

スキャンには 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が返したもの、またはユーザーが貼り付けるか伝えたものを使います。チャットではマスクしたプレビューのみを表示してください。プロジェクト、そのファイル、または環境からキーを探さないでください。

参考資料

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