matrixscan-batch-web

MatrixScan Batch Web スキル

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

学習データに含まれる Scandit SDK API の情報は、古くなっていたり、誤っていたりする可能性があります。BarcodeBatch Web API はメジャー SDK バージョン間で変更されており、コンストラクターのシグネチャー、オーバーレイのファクトリー名、非同期処理のパターン、初期化方法はすべて進化しています。

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

注意すべき Web 特有の落とし穴：

• BarcodeBatch.forContext(context, settings) は非同期です。必ず await を付けてください。new BarcodeBatch(settings) は使用しないでください（これは React Native ≥7.6 の形式です）。
• barcodeBatch.setEnabled(true/false) は非同期です。必ず await を付けてください。
• BarcodeBatchBasicOverlay.withBarcodeBatchForView(barcodeBatch, view) と BarcodeBatchBasicOverlay.withBarcodeBatchForViewWithStyle(barcodeBatch, view, style) は非同期のファクトリーメソッドです。必ず await を付けてください。暗黙的なオーバーレイはありません。
• BarcodeBatchAdvancedOverlay.withBarcodeBatchForView(barcodeBatch, view) は非同期です。必ず await を付けてください。
• BarcodeBatchAdvancedOverlay の setAnchorForTrackedBarcode と setOffsetForTrackedBarcode は同期処理（void を返します）です。await を付けないでください。
• BarcodeBatchAdvancedOverlay の clearTrackedBarcodeViews() も同期処理（void を返します）。
• BarcodeBatch.recommendedCameraSettings はメソッド呼び出しではなく、静的プロパティです。
• モジュールローダーは barcodeCaptureLoader()（@scandit/web-datacapture-barcode からインポート）です。個別の barcodeBatchLoader はありません。BarcodeCapture と BarcodeBatch は同じローダーを使用します。
• BarcodeBatch ではマルチスレッドが必須です。 Cross-Origin-Opener-Policy: same-origin と Cross-Origin-Embedder-Policy: require-corp がないと、SDK はシングルスレッドモードにフォールバックし、バッチトラッキングの速度が遅すぎて使用できません。SDK を jsDelivr CDN から読み込む場合も require-corp は機能します。credentialless は推奨しないでください。ページコードでは、await DataCaptureContext.forLicenseKey() の前に、@scandit/web-datacapture-core の BrowserHelper.checkMultithreadingSupport() を await せずに開始してください。これにより両方が並行して実行され、セットアップがチェックを待つことはありません。結果が false の場合、ユーザーがシングルスレッドでの実行を希望していない限り、マルチスレッドのダイアログを表示してください。references/integration.md の multithreading-warning ヘルパーモジュールから showMultithreadingWarning をインポートしてください。ページにマークアップを追加する必要はありません。React では、ヘルパーをインポートするのではなく、コンポーネントの状態から同じダイアログをレンダリングしてください。このダイアログはページの読み込みごとに最大1回だけ表示され、「このセッションでは再度表示しない」チェックボックスの設定を尊重します。COEP の credentialless はシングルスレッドで実行するという意味ではありません。Safari はこれをサポートしていないため、Safari ではダイアログが引き続き表示されます。
• ウェブ上の AR ビューでは、通常の HTML 要素を使用します。 TrackedBarcodeView.withHTMLElement(element, options) は Promise<TrackedBarcodeView> を返します。この Promise を setViewForTrackedBarcode に直接渡すか、viewForTrackedBarcode から返してください。どちらも Promise を受け入れます。これはサブクラスを使うパターンではありません。
• session.removedTrackedBarcodes は string[]（文字列としてシリアル化された識別子）を返します。TrackedBarcode.identifier（number）と比較する場合は、Number.parseInt(id, 10) を使用してください。
• DataCaptureView はコンテキストの初期化前に作成できます。new DataCaptureView() → connectToElement(element) → await view.setContext(context) の順に実行してください。これにより、SDK の読み込み中に進行状況バーを表示できます。代わりに await DataCaptureView.forContext(context) を使用しても問題ありません。
• view.connectToElement() に渡す DOM 要素には、定義済みのサイズと設定済みの position（例：fixed または absolute）が必要です。サイズがゼロのコンテナーや位置が設定されていないコンテナーでは、カメラのプレビューは表示されません。
• await context.frameSource?.switchToDesiredState(FrameSourceState.On) でカメラをオンにし、FrameSourceState.Off でオフにしてください。visibilitychange ハンドラーは追加しないでください。DataCaptureView はページが非表示の間にカメラを停止し、再び表示されたときに再開します。ハンドラーを追加すると、SDK 独自の処理と競合します。
• SDK を CDN から読み込む場合は、インポートマップと libraryLocation のすべての URL で、1つの正確なバージョン（例：@8.6.1）を指定してください。可変の @8 を指定すると、JavaScript とエンジンで異なるリリースが解決され、起動に失敗します。
• DataCaptureContext.forLicenseKey() は冪等なので、再度呼び出しても安全です。コンテキストをキャッシュする代わりに DataCaptureContext.sharedInstance を使用してください。dispose() はコンテキスト、そのエンジン、カメラを解放します。解放後にスキャンを再開する場合は、再度 forLicenseKey() を呼び出してください。

インテントルーティング

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

• MatrixScan Batch を一から統合する（例：「ウェブアプリに MatrixScan を追加する」、「BarcodeBatch を設定する」、「複数のバーコードを同時に追跡する」、「バーコードに AR オーバーレイを表示する」、「バーコードごとのブラシカラー」、「ライフサイクルまたはクリーンアップ」）→ references/integration.md を読み、そこに記載された手順に従ってください。
• 既存の MatrixScan Batch 統合を移行またはアップグレードする（例：「v6 から v7 にアップグレードする」、「BarcodeTracking から BarcodeBatch に移行する」、「Scandit SDK を v8 に上げる」、「SDK バージョン間の変更点」）→ references/migration.md を読み、そこに記載された手順に従ってください。
• サードパーティ製のマルチバーコードスキャナーを MatrixScan Batch に置き換える（例：「ZXing-js / @zxing/library の連続スキャナーを MatrixScan Batch に置き換える」、「BrowserMultiFormatReader の複数スキャンから BarcodeBatch に移行する」、「[ウェブ用バーコードライブラリ]の連続的な複数結果スキャンから BarcodeBatch に切り替える」）→ references/third-party-migration.md を読み、そこに記載された手順に従ってください。

API の使用ポリシー

以下の Scandit リファレンスに明示的に記載されている API のみを使用してください。メソッドシグネチャ、パラメーター、プロパティ名、インポートを創作したり、推測したりしないでください。API の有無や呼び出し方が不明な場合、またはコンパイルエラーが発生した場合は、回答する前に該当するリファレンスページを取得してください。ユーザーに自分でドキュメントを確認するよう案内しないでください。回答の後には、ユーザーがさらに詳しく確認できるよう、必ず関連リンクを含めてください。

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

1. まず、すでに取得したページに直接リンクがあるか確認してください。トピックページには、関連する API シンボルへの直接リンクがあります。
2. 直接リンクが見つからない場合は、API インデックス（下の表の完全な API リファレンスを参照）を取得し、そこから実際のリンクを抽出して開いてください。

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

ライセンスキー

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

以下の順序で進めてください。MCP が使えないことを理由に、ユーザーの作業を止めないでください。

1. Scandit MCP サーバーが接続されている場合 — product に sdk、platforms に webassembly、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 が返したキー、またはユーザーが貼り付けた、もしくは伝えたキーです。チャットに表示するのはマスクしたプレビューのみとしてください。プロジェクト、そのファイル、環境内でキーを探してはいけません。

参考資料

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

トピック	リソース
はじめに	はじめに · シンプルなサンプル · AR バブルのサンプル
高度なトピック（AR オーバーレイ、ブラシのカスタマイズ）	AR オーバーレイの追加
マルチスレッド／COOP+COEP ヘッダー	実行時パフォーマンスの向上
SDK のメジャーバージョン間の移行	6 → 7 · 7 → 8
API リファレンス全体	BarcodeBatch API