matrixscan-ar-web

MatrixScan AR Web スキル

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

トレーニングデータには、古い、または誤った Scandit SDK API が含まれている可能性があります。BarcodeAr* Web API は React Native API とは大きく異なり、初期化パターン、ビューの作成、プロバイダーのコールバックシグネチャがそれぞれ異なります。

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

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

• DataCaptureContext.forLicenseKey() は副作用として DataCaptureContext.sharedInstance を設定するため、戻り値を保存する必要はありません。アプリ全体で DataCaptureContext.sharedInstance を使ってコンテキストにアクセスしてください。
• BarcodeAr.forContext(DataCaptureContext.sharedInstance, settings) は非同期です。必ず await を付けてください。new BarcodeAr(settings) は使わないでください（これは React Native ≥7.6 での形式です）。
• BarcodeArView.create(element, context, barcodeAr) は非同期です。必ず await を付けてください。element 引数には、ビューを挿入する DOM コンテナーを指定します。
• BarcodeArView はHTML 要素（ScanditHTMLElement を継承）で、指定されたコンテナーに自分自身を追加します。barcodeArView.remove() を呼び出してクリーンアップしてください。このメソッドは要素を DOM から削除します。
• **ウェブではプロバイダーに戻り値ではなくコールバックパターンを使用します。**シグネチャは highlightForBarcode(barcode, callback) と annotationForBarcode(barcode, callback) です。結果は callback(highlight)／callback(annotation) で渡してください。戻り値として返さないでください。これは、Promise を返す非同期関数を使う React Native とは異なります。
• await barcodeArView.start() を明示的に呼び出す必要があります。create() の後にビューが自動的に開始されることはありません。
• ScanditIconBuilder.build() は Promise<ScanditIcon> を返すため、ウェブではアイコンの構築は非同期です。new ScanditIconBuilder().withIcon(ScanditIconType.Checkmark).build() を使用してください。静的な forType() メソッドはなく、ScanditIconType.Info も存在しません。列挙型の全 31 値は references/integration.md に記載されています。
• BarcodeArResponsiveAnnotation.threshold は静的プロパティです。BarcodeArResponsiveAnnotation.create(barcode, closeUp, far) を呼び出す前に設定してください。
• BarcodeArView はカメラを内部で管理します。Camera の手動セットアップ、context.setFrameSource、switchToDesiredState は行わないでください。このパターンは BarcodeBatch 用であり、BarcodeAr 用ではありません。
• **DataCaptureView は必要ありません。**MatrixScan AR では BarcodeArView.create() が DataCaptureView を完全に置き換えます。
• モジュールローダーは barcodeCaptureLoader()（@scandit/web-datacapture-barcode のもの）です。BarcodeAr 専用のローダーはありません。
• カスタムのハイライト／アノテーション要素は、HTMLElement を継承する Web Components として BarcodeArHighlight／BarcodeArAnnotation を実装する必要があります。position: absolute と will-change: transform を設定し、SDK が毎フレーム呼び出す updatePosition(point, transformOrigin, rotationAngle) を実装してください。SDK による表示管理のために [hidden] { display: none } を追加してください。if (!customElements.get(tag)) でガードし、customElements.define で一度だけ登録してください。
• session.addedTrackedBarcodes は Record<string, TrackedBarcode>（辞書）を返し、配列ではありません。反復処理には Object.values(session.addedTrackedBarcodes) を使用してください。session.allTrackedBarcodes も同様です。
• **マルチスレッドは必須です。**SDK を jsDelivr CDN から読み込む場合も、Cross-Origin-Opener-Policy: same-origin と Cross-Origin-Embedder-Policy: require-corp を設定してください。credentialless は推奨しないでください。これらのヘッダーがない場合、SDK はシングルスレッドモードにフォールバックしますが、AR トラッキングには遅すぎます。ページのコードでは @scandit/web-datacapture-core の BrowserHelper.checkMultithreadingSupport() を、await DataCaptureContext.forLicenseKey() の前に待機せずに開始してください。これにより 2 つが並行して実行され、セットアップがチェックの完了を待つことはありません。結果が false で、ユーザーがシングルスレッド実行を選択していない場合は、マルチスレッドのダイアログを表示してください。references/integration.md の multithreading-warning ヘルパーモジュールから showMultithreadingWarning をインポートしてください。このヘルパーにページのマークアップは不要です。React では、ヘルパーをインポートする代わりにコンポーネントの状態から同じダイアログをレンダリングしてください。このダイアログはページの読み込みごとに最大 1 回だけ表示され、「このセッションでは再び表示しない」チェックボックスを尊重します。COEP の credentialless はシングルスレッドで実行する指示ではありません。Safari はこれをサポートしていないため、Safari では引き続きダイアログが表示されます。
• SDK を CDN から読み込む場合は、インポートマップと libraryLocation のすべての URL で、正確なバージョン（例：@8.6.1）を固定してください。変動する @8 では JavaScript とエンジンが異なるリリースに解決され、起動に失敗します。
• visibilitychange ハンドラーを追加しないでください。ページが非表示の間はビューがカメラを停止し、ページが再び表示されると再開します。
• DataCaptureContext.forLicenseKey() は冪等なので、再度呼び出しても安全です。context.dispose() の後は forLicenseKey() を再度呼び出し、start() の前に BarcodeAr と BarcodeArView を再セットアップしてください。start() だけでは破棄済みのコンテキストは再起動しません。

インテントの振り分け

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

• MatrixScan AR をゼロから統合する（例：「ウェブアプリに MatrixScan AR を追加する」「BarcodeAr を設定する」「バーコードに AR のハイライトを表示する」「情報アノテーションを表示する」「ウェブで BarcodeArView を使う方法」「ライフサイクルやクリーンアップ」）→ references/integration.md を読み、そこに記載された手順に従ってください。
• BarcodeBatch / BarcodeTracking から BarcodeAr に移行する（例：「BarcodeBatch から BarcodeAr に移行する」「MatrixScan Batch を MatrixScan AR に変換する」「BarcodeTracking を BarcodeAr に置き換える」）→ references/migration.md を読み、そこに記載された手順に従ってください。

API の使用ポリシー

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

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

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

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

ライセンスキー

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

以下の順に進めてください。MCP の利用をユーザーに強制してはいけません。

1. Scandit MCP サーバーに接続されている場合 — ensure_scanner_setup を、製品 sdk、プラットフォーム webassembly、app_identifier（アプリのバンドル ID またはアプリケーション ID。ウェブの場合は本番環境のドメインであり、localhost は不可）、環境変数 SCANDIT_LICENSE_KEY を指定して呼び出してください。返されたコマンドは実行しないでください。その後、その結果または 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 が返したもの、またはユーザーが貼り付けるか提供したものを使用します。チャットではマスクしたプレビューのみを表示してください。プロジェクト、そのファイル、環境からキーを探してはいけません。

リファレンス

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

トピック	リソース
はじめに	はじめに · シンプルなサンプル
マルチスレッド / COOP+COEP ヘッダー	ランタイムパフォーマンスの向上
API リファレンス全体	BarcodeAr API