matrixscan-batch-cordova

MatrixScan Batch Cordova スキル

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

トレーニングデータには、古い Scandit SDK API や誤った API が含まれている可能性があります。BarcodeBatch* API の仕様は SDK のメジャーバージョン間で変更されており、コンストラクターのシグネチャ、オーバーレイのコンストラクター、リスナーの形式はいずれも進化しています。

コードを記述または提案する前に、必ずこのスキルで提供されているリファレンスで API を確認してください。 記憶しているメソッドのシグネチャ、パラメーター、プラグイン名、プロパティ名に頼らないでください。

Cordova 固有の注意点：

• グローバル名前空間：Scandit SDK は window.Scandit で公開されます。実行時には Scandit.BarcodeBatch、Scandit.DataCaptureView などを使用してください。npm パッケージ（scandit-cordova-datacapture-*）はプラグインマニフェストであり、ES モジュールではありません。WebView で実行されるユーザーコードに import { ... } from 'scandit-cordova-datacapture-*' を出力しないでください。バンドラーを使う TypeScript プロジェクトでは、コンパイル時に型をインポートする場合に限り使用できます。
• deviceready による制御：すべての Scandit API は document.addEventListener('deviceready', ...) の後に呼び出す必要があります。モジュールの読み込み時には絶対に呼び出さないでください。
• context.setMode(barcodeBatch)：コンテキストにモードを登録するための Cordova メソッドです。以前に有効だったモードは置き換えられます。両方の Cordova サンプルで確認済みです。
• 最新のコンストラクターには SDK 7.6 以降が必要です：new Scandit.BarcodeBatch(settings)、new Scandit.BarcodeBatchBasicOverlay(mode, style)、new Scandit.BarcodeBatchAdvancedOverlay(mode)、Scandit.BarcodeBatch.createRecommendedCameraSettings() はすべて cordova=7.6 以降で使用できます。
• AdvancedOverlay はシリアライズされたビューを使用します：Cordova では、setViewForTrackedBarcode は view: Promise<TrackedBarcodeView?> を受け取ります。これはネイティブ UI インスタンスではなく、シリアライズされた TrackedBarcodeView です。Scandit.TrackedBarcodeView.withHTMLElement(domElement, options) を使って作成してください。形式は Capacitor と同じです。正確なパターンは Bubbles サンプルを参照してください。
• MatrixScan AR アドオンが必要です：BarcodeBatchAdvancedOverlay、IBarcodeBatchBasicOverlayListener.brushForTrackedBarcode、setBrushForTrackedBarcode を使用するには、MatrixScan AR アドオンのライセンスが必要です。
• カメラ権限は、iOS と Android の両方でプラグインによって自動的に設定されます。
• DataCaptureView.forContext(context) は Cordova のファクトリーです。その後、view.connectToElement(htmlElement) を呼び出して DOM にアタッチします。
• TrackedObject（Cordova 8.2 以降）：SDK 8.2 以降では、TrackedBarcode が継承する基底クラス TrackedObject が導入されています。追加の手順は不要です。日常的に使用する TrackedBarcode API に変更はありません。

インテントの振り分け

ユーザーのリクエストに応じて、回答する前に適切なリファレンスファイルを読み込んでください。

• MatrixScan Batch をゼロから統合する（例：「アプリに MatrixScan を追加したい」「BarcodeBatch を設定したい」「複数のバーコードを同時に追跡したい」「AR オーバーレイを表示したい」「バーコードごとのブラシ」「タップ処理」「削除されたバーコード」「フィードバック／ビープ音／振動」「ライフサイクルまたはクリーンアップ」「カメラ権限」）→ references/integration.md を読み、記載の手順に従ってください。
• 既存の MatrixScan 統合を移行またはアップグレードする（例：「v6 から v7/v8 にアップグレードしたい」「BarcodeTracking から BarcodeBatch に移行したい」「BarcodeTracking と BarcodeBatch は同じか」「Scandit プラグインを更新したい」「SDK バージョン間の変更点は？」）→ references/migration.md を読み、記載の手順に従ってください。
• サードパーティ製の複数バーコードスキャナーを置き換える（例：「phonegap-plugin-barcodescanner を MatrixScan Batch に置き換えたい」「Cordova ML Kit バーコードプラグインから移行したい」「スキャナーをループしてすべてのバーコードを読み取っているので、Scandit に切り替えたい」）→ references/third-party-migration.md を読み、記載の手順に従ってください。

API の使用ポリシー

以下の Scandit リファレンスで明示的に文書化されている API のみを使用してください。メソッドのシグネチャ、パラメーター、プロパティ名、インポートを創作したり、推測したりしないでください。API が存在するかどうか、または呼び出し方法が不確かな場合、あるいは実行時エラーが発生した場合は、回答する前に該当するリファレンスページを取得してください。ユーザー自身にドキュメントを確認するよう伝えてはいけません。回答の後には、ユーザーがさらに調べられるよう、必ず関連リンクを含めてください。

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

1. まず、すでに取得したページにそのページへの直接リンクがあるか確認します。
2. 直接リンクが見つからない場合は、API インデックスを取得し、実際のリンクを取り出してから、そのリンクを開きます。

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

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

Cordova は WebView ベースのフレームワークです。このスキルの例では、（任意で JSDoc 型ヒントを使用した）プレーン JavaScript を使用します。同じ API は TypeScript でも動作します。global.d.ts 宣言ファイルを追加し、TypeScript の構文で記述してください。このスキルでは、デフォルトで TypeScript プロジェクトを想定していません。対象のプロジェクトが明らかに TypeScript（.ts ファイル、tsconfig.json）の場合は、最終的な出力を TypeScript に合わせてください。それ以外の場合は、プレーン JS を使用してください。

ライセンスキー

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

以下の手順を順番に進めてください。MCP が原因でユーザーを待たせてはいけません。

1. Scandit MCP サーバーが接続されている場合 — 製品に native、プラットフォームに ios と 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：~/.cursor/mcp.json に {"mcpServers": {"scandit": {"url": "https://ssl.scandit.com/mcp"}}} を追加します。
   • VS Code：MCP ユーザー設定に {"servers": {"scandit": {"type": "http", "url": "https://ssl.scandit.com/mcp"}}} を追加します。

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

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

その後、プレースホルダーの代わりにキーをコードに設定してください。.env にキーを入れただけでは、アプリには渡りません。Cordova は .env を自動的に読み込まないため、以下の最も簡単な方法を使用してください。どのプラットフォームでも最も簡単な方法は、.env を読み込んでライセンスキーの呼び出しにキーを直接設定することです。その際も、チャットに表示するのはマスク済みのプレビューのみにしてください。

リファレンス

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

トピック	リソース
Cordova のはじめ方	はじめに
Cordova の AR オーバーレイ	AR オーバーレイの追加
Bubbles のサンプル	MatrixScanBubblesSample
API リファレンス全体	BarcodeBatch API