label-capture-rn

Label Capture React Native スキル

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

学習データには、古くなった、または正しくない Scandit Label Capture API が含まれている場合があります。Label Capture は最近の SDK リリースで進化しており、React Native プラグインのインターフェース（インポート、ネイティブリンク、pod install、パッケージ名）にも、Web SDK とは異なる独自の規則があります。

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

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

• React Native ではリスナーメソッド名に iOS 形式を使用します。 Validation Flow リスナーでは didCaptureLabelWithFields(fields) と didSubmitManualInputForField(field, oldValue, newValue) を使用します。Web 版に相当する onValidationFlowLabelCaptured／onManualInput ではありません。Web 形式のリスナー名が提案されていたら、React Native では誤りです。
• DataCaptureContext.initialize(licenseKey) は、他の Scandit API より前に必ず一度だけ呼び出す必要があります。これにより、他のすべての要素が参照するシングルトン DataCaptureContext.sharedInstance が設定されます。複数のコンテキストを作成しないでください。（公式の LabelCaptureSimpleSample では従来の DataCaptureContext.forLicenseKey(...) 形式が使われています。どちらも動作しますが、新しい統合では、他の v8 RN ドキュメントと一貫性を保つため initialize を使用してください。）
• iOS では、Scandit パッケージをインストールまたはアップグレードするたびに、npx [email protected]（または cd ios && pod install）を実行する必要があります。Android では Gradle により自動リンクされます。
• Metro のバンドラーキャッシュにより、Scandit パッケージのアップグレードが反映されないことがよくあります。プラグインのバージョンを上げた後、再ビルドしても古い動作が見られる場合は、Metro を --reset-cache 付きで起動してください。
• iOS（ios/<App>/Info.plist の NSCameraUsageDescription）と Android（PermissionsAndroid による実行時リクエスト）の両方でカメラ権限が必要です。プラグインがマニフェストの権限を自動的に宣言します。
• RN でのフィールド定義はビルダー形式ではなく、クラスベースです。CustomBarcode.initWithNameAndSymbologies(name, [...])、new ExpiryDateText(name)、field.optional = true、LabelCaptureSettings.settingsFromLabelDefinitions([...], {}) を使用します。LabelCaptureSettingsBuilder／LabelDefinitionBuilder や v8.5 のファクトリー関数の糖衣構文はありません。これらは Web 専用です。

製品の推奨事項

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

• デフォルトでは Validation Flow を使用します。 新しい統合では、LabelCaptureBasicOverlay ではなく LabelCaptureValidationFlowOverlay を使用してください。ライブ AR オーバーレイや、Validation Flow の固定レイアウトでは実現できない 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（下記の参考資料表のリンク）をクローンして適応するよう推奨してください。
• 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 に関する質問（例：「Validation Flow をカスタマイズするには？」「VF では何を変更できますか？」「なぜこのように実装されているのですか？」「手動編集にどう対応すればよいですか？」「色を変更できますか？」）→ references/validation-flow.md を読んでください。
• Validation Flow 以外のビジュアルカスタマイズ（例：「ライブ AR オーバーレイを表示したい」「キャプチャした各フィールドの横にタグを描画したい」「スキャン中にカメラフレームを取得するには？」）→ references/customization.md を読んでください。
• Adaptive Recognition Engine／クラウドへのフォールバック／レシートのスキャン（「ARE を有効にするには？」「クラウド認識を使いたい」「レシートをスキャンしたい」「AdaptiveRecognitionMode」「ARE は本番環境で利用できますか？」）→ references/adaptive-recognition.md を読んでください。
• 既存の Label Capture 統合を移行またはアップグレードする（例：「Label Capture を最新の SDK にアップグレードしたい」「Label Capture の SDK バージョン間で何が変わりましたか？」）→ references/migration.md を読み、そこに記載された手順に従ってください。

API 使用ポリシー

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

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

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

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

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

React Native アプリは、クラスコンポーネントまたは関数コンポーネントで記述できます。このスキルの例では、公式の LabelCaptureSimpleSample と現在の React Native の慣習に沿った、フックを使う関数コンポーネントを使用します。対象プロジェクト内に古いクラスコンポーネントが残っている場合でも、新しい Label Capture コードは関数コンポーネントで記述してください。アプリの他のコンポーネントのスタイルは書き換えず、Label Capture の統合部分のみ、現在の慣用的な書き方（useRef、useEffect、useMemo、ビューのプロパティ用の命令的な ref コールバック）を維持してください。

例は TypeScript（.tsx）です。対象プロジェクトがプレーンな JavaScript（.js／.jsx）の場合は、型注釈を削除し、インポートと構造はそのままにしてください。

ライセンスキー

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

以下の手順を順番に行ってください。MCP のためにユーザーの作業を止めないでください。

1. Scandit MCP サーバーに接続されている場合 — 製品に native、プラットフォームに ios と android、app_identifier（アプリのバンドル ID またはアプリケーション ID。ウェブの場合は本番ドメインで、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 が返したキー、またはユーザーが貼り付けるか伝えたキーを記述してください。チャットには引き続き、マスクしたプレビューのみを表示してください。キーを探すために、プロジェクト、ファイル、環境を検索しないでください。

参考資料

質問の内容に応じて、ユーザーを適切なリソースに案内します。

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