matrixscan-ar-capacitor

MatrixScan AR Capacitor スキル

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

学習データには、古い、または誤った Scandit SDK API が含まれている可能性があります。BarcodeAr API は Capacitor 8.2 で新たに追加されたため、参照できる Capacitor での過去の実装はありません。プロパティ、コンストラクターのシグネチャー、プロバイダーのインターフェイス、ビューのアタッチ方法は、他のプラットフォームや一般的な知識と異なる場合があります。

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

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

• ScanditCaptureCorePlugin.initializePlugins() は、DataCaptureContext の構築を含む、ほかのすべての Scandit API の前に呼び出し（完了を待機）する必要があります。呼び出しを忘れると、初期化とは無関係に見えるランタイムエラーが発生します。
• iOS／Android にネイティブの成果物を反映するため、プラグインのバージョンを変更するたびに npx cap sync を実行する必要があります。これを省略すると、実行時に Web とネイティブのバージョンが一致しなくなります。
• BarcodeArView には DOM 要素が必要です。 SparkScan とは異なり、BarcodeArView は浮動するネイティブオーバーレイではありません。DOM 要素からサイズと位置を取得します。HTML 内の <div id="barcode-ar-view"> コンテナーにアタッチするには、await barcodeArView.connectToElement(element) を呼び出す必要があります。
• Capacitor で BarcodeAr を使用する場合の最小 SDK バージョンは 8.2 です。このプラットフォームには、移行元となる v6 や v7 の履歴はありません。
• BarcodeAr は new BarcodeAr(settings) で構築します。コンテキストは BarcodeArView を介して別途接続し、モードのコンストラクターには渡しません。
• カメラは BarcodeAr.createRecommendedCameraSettings()、Camera.withSettings(cameraSettings)、context.setFrameSource(camera) を使って明示的に設定します。実行開始後のカメラのライフサイクルは BarcodeArView が管理します。
• highlightProvider と annotationProvider は、非同期メソッドを持つ単純なオブジェクトです。BarcodeArView インスタンスのプロパティとして設定します。
• iOS では Info.plist に NSCameraUsageDescription が必要です。Android ではカメラの権限が自動的に処理されます。

インテントの振り分け

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

• MatrixScan AR を一から統合する場合（例：「アプリに MatrixScan AR を追加したい」「Barcode AR を設定したい」「Capacitor で BarcodeArView を使う方法」「アノテーションを表示する方法」「バーコードをハイライトする方法」）→ references/integration.md を読み、記載された手順に従ってください。

• BarcodeBatch／BarcodeTracking から BarcodeAr に移行する場合（例：「BarcodeBatch のコードを移行したい」「BarcodeTracking を BarcodeAr に置き換えたい」「MatrixScan から BarcodeAr にアップグレードしたい」、対象ファイルが BarcodeBatch、BarcodeBatchBasicOverlay、BarcodeBatchAdvancedOverlay、TrackedBarcodeView をインポートしている、または BarcodeBatch インスタンスを使って context.setMode( を呼び出している）→ references/migration.md を読み、記載された 10 ステップの移行プロセスに従ってください。

API の使用ポリシー

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

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

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

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

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

Capacitor は WebView ベースのフレームワークです。このスキルの例では**プレーン JavaScript（ES モジュール）**を使用します。TypeScript プロジェクトでも同じインポートと API をそのまま使用できます。型を追加するだけですが、このスキルではデフォルトで TypeScript プロジェクトを想定していません。対象プロジェクトが明らかに TypeScript（.ts ファイル、tsconfig.json）の場合は、最終出力を TypeScript の構文に合わせてください。それ以外の場合はプレーン JS を使用してください。

ライセンスキー

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

以下の手順を順番に実行してください。MCP のためにユーザーを待たせてはいけません。

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

リファレンス

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

トピック	リソース
Capacitor の統合	はじめに · サンプル
完全な API リファレンス	BarcodeAr API