label-capture-android

Label Capture Android スキル

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

学習データには、古い、または誤った Scandit Label Capture API が含まれている可能性があります。Label Capture は、最近の SDK リリースで進化しています。

• v7→v8 のメジャーアップデートで、LabelFieldDefinition の正規表現ビルダーメソッドの名前が変更されました（setPattern→setValueRegex、setPatterns→setValueRegexes、setDataTypePattern→setAnchorRegex、setDataTypePatterns→setAnchorRegexes）。
• v8.2 では、Validation Flow 2.0 によって LabelCaptureValidationFlowOverlay に shouldHandleKeyboardInsetsInternally が導入されました。これは Android 15 のエッジツーエッジ強制に関係します。
• Android のシンボロジー名ではアンダースコアを使用します。Symbology.EAN13UPCA ではなく、Symbology.EAN13_UPCA です。

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

Label Capture は見た目以上に幅広く対応しています — 失敗の大半を防ぐための 2 つの習慣

Label Capture には、実際にスキャンされるデータ（シリアル番号、IMEI 1 と 2、有効期限／梱包日、価格、重量、VIN、7 セグメントディスプレイ）に対応する豊富な事前構築済みフィールドと事前構築済みラベル定義全体が用意されています。統合でよく起こる問題は、これらの存在を忘れることと、モデルアーティファクトが欠けているために実行時にクラッシュすることです。次の 2 つを習慣にしてください。

1. 何かを独自に組み立てる前に、事前構築済みフィールドまたは事前構築済みラベルを利用してください。 ユーザーがスキャン対象として認識しやすいもの（「シリアル番号」、「IMEI」、「有効期限」、「価格／棚札」、「VIN」など）を挙げた場合、通常はアンカー／値の正規表現が調整済みの専用ビルダー、またはラベル全体のファクトリーが用意されています。それを使ってください。事前構築済みビルダーがあるものに対して、手書きの正規表現を使ってカスタムバーコード／テキストフィールドを作成するのは、統合を誤る最大の原因です。推測した正規表現は、実際のラベルに対して調整済みの正規表現ほど適切に一致せず、事前構築済みのものを知らなかったことも示してしまいます。事前構築済みのものが合わない場合に限り、addCustomBarcode()／addCustomText() を使用してください。すべてのカタログと振り分けルールは references/integration.md に記載されています。記憶に頼らず、参照してください。

2. 事前構築済みフィールドまたは定義を使う場合は、適切なモデルアーティファクトを必ずバンドルしてください。これを誤ることが、実行時の失敗の第 1 位です。 label-text-models はテキストフィールド専用ではありません。シリアル番号、IMEI、部品番号のフィールドは「バーコード」フィールドですが、実行時にモデルを読み込みます。また、事前構築済みのラベル全体のファクトリーには、label-text-models だけでは不十分です。createPriceCaptureDefinition にはさらに com.scandit.datacapture:price-label が必要です。これを追加し忘れると、アプリはコンパイルされて起動しますが、スキャンできません。references/integration.md にフィールドごと、ファクトリーごとのアーティファクト要件が記載されています。Gradle ブロックを作成する前に、使用する事前構築済みのものすべてについて、必要なアーティファクトを確認してください。

制約：Label Capture と Barcode Capture は同時に実行できません

DataCaptureContext で同時に実行できるモードは 1 つだけなので、Label Capture と Barcode Capture は同時にアクティブにできません。両方をアタッチすると、コンテキストでエラーが発生します。ユーザーがラベルに加えて単独のバーコードも読み取りたい場合は、2 つ目のモードを追加するのではなく、そのバーコードをラベル定義内のフィールド（addCustomBarcode() または事前構築済みのバーコードフィールド）としてモデル化してください。ほとんどの場合、これが適切な方法です。（本当に 2 つの独立したスキャン手順が必要な場合に限り、setMode() でアクティブなモードを切り替えます。）references/integration.md を参照してください。

インテントルーティング

ユーザーのリクエストに基づいて、回答する前に適切なリファレンスファイルを読み込みます。

• Label Capture をゼロから統合する（例：「Android アプリに Label Capture を追加する」「バーコードと有効期限を含む価格タグをスキャンする」「携帯電話の箱にあるシリアル番号／IMEI をスキャンする」「VIN を読み取る」「Smart Label Capture の使い方」）→ references/integration.md を読み、そこに記載されている手順に従います。このファイルには、事前構築済みのフィールドカタログ全体と事前構築済みのラベル全体の定義が含まれています。カスタムフィールドや正規表現を作成する前に、必ず参照してください。
• Validation Flow を有効化またはカスタマイズする（例：「Validation Flow を有効にする方法」「Validation Flow のオーバーレイを追加する」「Validation Flow のプレースホルダーテキスト／ボタンラベルをカスタマイズする」「Validation Flow の結果を処理する方法」）→ references/validation-flow.md を読み、そこに記載されている手順に従います。
• オーバーレイのカスタマイズ、カスタム AR ビューの追加、トラブルシューティング、またはクラウド Adaptive Recognition（例：「フィールドのハイライトブラシ／labelBrush をカスタマイズする」「価格フィールドが正しい場合は緑色にする」「キャプチャしたラベルを枠で囲む」「フィールドの上にチェックマーク／バッジ／アイコンを表示する」「LabelCaptureBasicOverlayListener／brushForField／brushForLabel を使う」「Advanced Overlay でフィールド上にカスタム AR ビューを追加する」「viewForCapturedLabel(Field)」「7 セグメントディスプレイをスキャンする」「カメラプレビューが黒い」「ラベルの構築時にアプリが起動時にクラッシュする」「クラウドフォールバック／Adaptive Recognition Engine／ARE を有効にする」「レシートをスキャンする」）→ references/advanced.md を読みます（オーバーレイのカスタマイズと構成、Advanced Overlay（フィールド単位のリスナーにはラベルコンテキストがないという注意点を含む）、7 セグメント、Adaptive Recognition、レシートスキャンのベータ版）。トラブルシューティングの症状については、references/integration.md の末尾で説明しています。
• 既存の Label Capture 統合を移行またはアップグレードする（例：「Label Capture を最新の SDK にアップグレードする」「v7 から v8 に移行する」「Label Capture の SDK バージョン間で何が変わったか」「アップグレード後、Validation Flow でキーボードが入力欄に重なる」「Validation Flow を 2.0 に移行する」）→ references/migration.md を読み、そこに記載されている手順に従います。

API 使用ポリシー

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

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

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

URL の構成は異なる場合があり、推測すると 404 エラーにつながります。

ライセンスキー

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

次の手順を順番に進めてください。MCP のためにユーザーを待たせないでください。

1. Scandit MCP サーバーが接続されている場合 — 製品に native、プラットフォームに android を指定して ensure_scanner_setup を呼び出し、続けて get_license_env_command が返すコマンドを実行して、キーをプロジェクトの .env に書き込みます。チャットでは、マスクされたプレビューのみを表示してください。キー全体を出力しないでください。

2. 接続されていない場合 — 一度だけ接続することを提案し、ステップ1に進みます。

   • Claude Code：claude mcp add --transport http scandit https://ssl.scandit.com/mcp
   • Cursor：{"mcpServers": {"scandit": {"url": "https://ssl.scandit.com/mcp"}}} を ~/.cursor/mcp.json に追加します
   • VS Code：{"servers": {"scandit": {"type": "http", "url": "https://ssl.scandit.com/mcp"}}} を MCP ユーザー設定に追加します

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

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

次に、プレースホルダーの代わりにキーをコードに設定します。キーを .env に入れただけでは、アプリには反映されません。Gradle でキーを読み取り、BuildConfig フィールドとして公開します（この設定には buildFeatures { buildConfig = true } が必要です）。どのプラットフォームでも最も簡単な方法は、.env を読み取り、ライセンスキーの呼び出しにキーを直接設定することです。その場合も、チャットではマスクされたプレビューのみを表示してください。

参考資料

質問に応じて、ユーザーに適切なリソースを案内してください。

トピック	リソース
基本的な統合	はじめに · サンプル（LabelCaptureSimpleSample）
ラベル定義（フィールド、正規表現、プリセット）	ラベル定義
高度なトピック（オーバーレイのカスタマイズ — ブラシ、フローティング AR ビュー — 7 セグメント表示、Adaptive Recognition／Receipt Scanning ベータ版）	references/advanced.md · 高度な設定
API リファレンス全体	Label Capture API