sparkscan-cordova

SparkScan Cordova スキル

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

学習データに、古くなった Scandit SDK API や誤った Scandit SDK API が含まれている可能性があります。SparkScan API は SDK のメジャーバージョン間で大きく変わるため、プロパティ名が変更、削除、再構成されることがあります。また、Cordova プラグインの仕様（グローバルな Scandit 名前空間、プラグインのインストールコマンド、deviceready のタイミング）も変化しています。

コードを記述または提案する前に、必ずこのスキルで提供されているリファレンスで 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 prepare を実行してください（必要に応じてプラットフォームを再インストールしてください）。これを省略すると、実行時のバージョン不一致が発生します。

意図の判定

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

• SparkScan を新規に統合する（例：「アプリに SparkScan を追加したい」「バーコードスキャンを設定したい」「Cordova で SparkScan を使うには」「SparkScan でフィードバックを処理するには」）→ references/integration.md を読み、そこに記載された手順に従ってください。
• 既存の SparkScan 統合を移行またはアップグレードする（例：「v6 から v7 にアップグレードしたい」「SparkScan を移行したい」「Scandit プラグインを v8 に上げたい」「SDK バージョン間の変更点は」）→ references/migration.md を読み、そこに記載された手順に従ってください。

API の使用ポリシー

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

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

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

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

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

Cordova は WebView ベースのフレームワークです。このスキルの例では、プレーンな JavaScript を使用します（公式の ListBuildingSample にあるように、JSDoc の型ヒントは任意で使用できます）。同じ API は TypeScript でも動作します。global.d.ts 宣言ファイル（references/integration.md で説明）を追加し、TypeScript の構文で記述してください。このスキルでは、デフォルトで TypeScript プロジェクトを想定しません。対象プロジェクトが明らかに TypeScript の場合（.ts ファイル、tsconfig.json がある場合）は、最終的な出力を TypeScript に合わせてください。それ以外の場合は、プレーンな JavaScript を使用してください。

ライセンスキー

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

次の手順を順番に進めてください。MCP の接続をユーザーに強要しないでください。

1. Scandit MCP サーバーに接続済みの場合 — 製品に native、プラットフォームに ios と android を指定して ensure_scanner_setup を呼び出し、続いて get_license_env_command が返すコマンドを実行して、キーをプロジェクトの .env に書き込みます。チャットで表示するのは、マスクしたプレビューだけにしてください。キー全体を表示してはいけません。

2. 接続されていない場合 — 一度接続するかどうかを提案し、接続後は手順 1 から続けてください。

   • Claude Code：claude mcp add --transport http scandit https://ssl.scandit.com/mcp
   • Cursor：{"mcpServers": {"scandit": {"url": "https://ssl.scandit.com/mcp"}}} を ~/.cursor/mcp.json に追加します。
   • VS Code：{"servers": {"scandit": {"type": "http", "url": "https://ssl.scandit.com/mcp"}}} を MCP ユーザー設定に追加します。

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

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

その後、プレースホルダーを置き換えてキーをコードに設定します。キーを .env に入れただけでは、アプリには反映されません。Cordova は .env を自動で読み込まないため、以下の最も簡単な方法を使ってください。どのプラットフォームでも最も簡単な方法は、.env を読み込んでライセンスキー呼び出しにキーを直接設定することです。この場合も、チャットに表示するのはマスクしたプレビューだけにしてください。

参考資料

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

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