sparkscan-capacitor

SparkScan Capacitor スキル

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

学習データには、古い Scandit SDK API や誤った Scandit SDK API が含まれている可能性があります。SparkScan API は SDK のメジャーバージョン間で大幅に変更されます。プロパティの名前が変更されたり、削除されたり、再構成されたりするほか、Capacitor プラグインの仕様（インポート、プラグインの初期化、ネイティブ同期の手順）も進化しています。

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

Capacitor 固有の注意点：

• ScanditCaptureCorePlugin.initializePlugins() は、DataCaptureContext の構築を含む、ほかの Scandit API を使用する前に必ず呼び出し（await）する必要があります。これを忘れると、初期化とは無関係に見えるランタイムエラーが発生します。
• iOS／Android にネイティブ成果物を反映するため、プラグインのバージョンを変更するたびに npx cap sync を実行する必要があります。実行しないと、実行時に Web とネイティブのバージョンが一致しなくなります。
• SparkScan は WebView の上にネイティブオーバーレイとして表示されます。スキャナーをマウントする DOM 要素はありません。ユーザーに <div id="scanner"> コンテナを追加するよう指示しないでください。

意図の振り分け

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

• SparkScan を一から統合する（例：「アプリに SparkScan を追加したい」、「バーコードスキャンを設定したい」、「Capacitor で SparkScan を使う方法を知りたい」、「SparkScan のフィードバック処理方法を知りたい」）→ references/integration.md を読み、そこに記載された指示に従います。
• 既存の SparkScan 統合を移行またはアップグレードする（例：「v6 から v7 にアップグレードしたい」、「SparkScan を移行したい」、「Scandit プラグインを v8 に更新したい」、「SDK のバージョン間で何が変わったか知りたい」）→ references/migration.md を読み、そこに記載された指示に従います。
• 他社製の単発スキャナーを置き換える（例：「@capacitor-mlkit/barcode-scanning / ML Kit から SparkScan に切り替えたい」、「BarcodeScanner.scan() を Scandit に置き換えたい」）→ references/third-party-migration.md を読み、そこに記載された指示に従います。

API 使用ポリシー

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

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

1. まず、すでに取得したページ（例：Advanced Configurations ページ）に、そのページへの直接リンクが含まれているか確認してください。トピックページには関連する API シンボルへの直接リンクがあります。取得を依頼する際は、コンテンツとともにリンクも必ず含めるようにしてください。
2. 直接リンクが見つからない場合は、API インデックス（下の表の Full API reference を参照）を取得し、そこから実際のリンクを見つけてたどってください。

URL の構造は SDK のバージョンやプラグインのパスによって異なります（例：api/ui/ サブディレクトリ）。URL を推測すると 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。ウェブの場合は本番ドメインで、localhost は指定しません）、env_var に SCANDIT_LICENSE_KEY を指定して ensure_scanner_setup を呼び出します。戻り値のコマンドは実行しないでください。次に、その結果または list_license_keys から取得したキーの ID を指定して get_license_key を呼び出します。list_license_keys でキーがトライアルではないとわかった場合は、取得する前にユーザーに確認してください。チャットに表示するのは、最大でもマスクしたプレビューだけにしてください。キー全体は絶対に出力しないでください。

2. 接続されていない場合 — リモート Scandit MCP サーバー https://ssl.scandit.com/mcp を MCP クライアントに接続できることを、ユーザーに一度だけ伝えてから、手順 1 に進みます。MCP クライアントの設定を自分で編集しないでください。

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

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

その後、キーをコードに設定します。プレースホルダーの代わりに、ライセンスキーを呼び出す箇所へキーを書き込みます。使用するのは、get_license_key が返したキー、またはユーザーが貼り付けるか提示したキーです。チャットに表示するのはマスクしたプレビューだけにしてください。キーを探すためにプロジェクト、ファイル、環境を検索しないでください。

参考資料

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

トピック	リソース
Capacitor との統合	はじめに · サンプル
高度なトピック（カスタムフィードバック、ハードウェアトリガー、スキャンモード、UI のカスタマイズ）	高度な設定
メジャー SDK バージョン間の移行	6 → 7 · 7 → 8
API リファレンス全文	SparkScan API