matrixscan-ar-cordova

MatrixScan AR Cordova スキル

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

トレーニングデータには、古い、または正しくない Scandit SDK API が含まれている可能性があります。BarcodeAr API は Cordova プラグイン 8.2 で新たに導入されたもので、Cordova の v6 や v7 には存在しません。参照できる移行履歴はありません。

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

Cordova 固有の注意点：

• Scandit SDK はグローバルな window.Scandit オブジェクトで公開されます。npm パッケージ名（scandit-cordova-datacapture-*）はプラグインマニフェストであり、実行時の ES モジュールではありません。WebView で実行されるユーザーコードに import { ... } from 'scandit-cordova-datacapture-*' を出力しないでください。代わりに Scandit.X を使用してください（型付けには必要に応じて global.d.ts を使用します）。パッケージから直接インポートするのは、Ionic／Angular／Webpack でバンドルされたプロジェクトのみです。
• Scandit API を安全に使用できるのは document.addEventListener('deviceready', ...) の後だけです。モジュールの読み込み時に Scandit の呼び出しを実行しないでください。Cordova ブリッジの準備が整っていないため、失敗します。
• Cordova の BarcodeArView はDOM オーバーレイモデルを使用します。ネイティブの AR ビューは、通常の HTML <div> 要素と同じサイズおよび位置になるように配置されます。ビューの構築後に barcodeArView.connectToElement(element) を呼び出して DOM ノードに紐付け、破棄時には barcodeArView.detachFromElement() を呼び出す必要があります。
• new Scandit.BarcodeAr(settings) は Cordova 用のコンストラクターです（BarcodeAr.forContext ではありません）。コンテキストは context.setFrameSource(camera) で別途設定します。
• Cordova の BarcodeAr では、カメラを手動で管理します。Scandit.Camera.withSettings(Scandit.BarcodeAr.createRecommendedCameraSettings()) で取得し、フレームソースとして設定したうえで、開始／停止時に camera.switchToDesiredState(Scandit.FrameSourceState.On/Off) を呼び出します。
• ハイライトプロバイダーとアノテーションプロバイダーは、それぞれ Promise<BarcodeArHighlight | null> と Promise<BarcodeArAnnotation | null> を返します。メソッドを async にするか、Promise を明示的に返してください。
• プラグインのバージョンを変更した後は、新しいネイティブアーティファクトを反映するため、cordova prepare を実行してください（必要に応じてプラットフォームも再インストールします）。

インテントの振り分け

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

• MatrixScan AR を最初から統合する（例：「アプリに MatrixScan AR を追加したい」「AR バーコードオーバーレイを設定したい」「Cordova で BarcodeAr を使う方法は？」「情報アノテーションを表示するには？」「ハイライトをカスタマイズするには？」）→ references/integration.md を読み、記載されている手順に従ってください。

• BarcodeBatch／BarcodeTracking から BarcodeAr に移行する（例：「MatrixScan コードを移行したい」「BarcodeBatch から BarcodeAr に更新したい」「BarcodeBatchBasicOverlay／BarcodeBatchAdvancedOverlay を使っている」「古い MatrixScan 統合を変換したい」「BarcodeTracking を使用しており、アップグレードが必要」）→ references/migration.md を読み、記載されている 10 ステップの移行ガイドに従ってください。Cordova 固有の重要な注意点：BarcodeArCustomAnnotation はCordova では利用できません。BarcodeBatchAdvancedOverlay の自由形式 HTML オーバーレイは、組み込みのアノテーションタイプ（BarcodeArInfoAnnotation、BarcodeArPopoverAnnotation、BarcodeArStatusIconAnnotation、BarcodeArResponsiveAnnotation）に置き換える必要があります。

API 使用ポリシー

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

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

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

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

フレームワークの種類に関するポリシー

Cordova は WebView ベースのフレームワークです。このスキルの例では、プレーン JavaScript（公式の MatrixScanARSimpleSample にあるような、任意の JSDoc 型ヒントを含む）を使用します。同じ API は TypeScript でも動作します。global.d.ts 宣言ファイル（references/integration.mdで説明）を追加し、TypeScript の構文で記述してください。このスキルでは、デフォルトで 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 が返したもの、またはユーザーが貼り付けるか伝えたものを使用します。チャットではマスクしたプレビューのみを表示してください。キーを探すために、プロジェクト、そのファイル、環境を検索しないでください。

リファレンス

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

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