sparkscan-web

SparkScan Web スキル

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

学習データに含まれる Scandit SDK API の情報は、古くなっていたり、誤っていたりする可能性があります。SparkScan API は SDK のメジャーバージョン間で大幅に変更され、プロパティの名前変更、削除、構成変更が行われています。

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

Web 固有の注意事項：

• スキャンを一時停止するために visibilitychange ハンドラーを追加しないでください。ページが非表示になると、SparkScanView はすでにアイドル状態に切り替わります。
• SDK を CDN から読み込む場合は、import map と libraryLocation のすべての URL で、正確なバージョン（例：@8.6.1）を指定してください。バージョンを固定しない @8 を使うと、JavaScript とエンジンで異なるリリースが解決され、起動に失敗します。
• クロスオリジン分離には、SDK を jsDelivr CDN から読み込む場合も、Cross-Origin-Opener-Policy: same-origin と Cross-Origin-Embedder-Policy: require-corp が必要です。SDK で credentialless を推奨しないでください。ページのコードでは、await DataCaptureContext.forLicenseKey() の前に、@scandit/web-datacapture-core の BrowserHelper.checkMultithreadingSupport() を待機せずに開始してください。これにより両方が並行して実行され、セットアップがチェックを待つことはありません。結果が false で、ユーザーがシングルスレッドでの実行を指定していない場合は、マルチスレッドのダイアログを表示してください。references/integration.md の multithreading-warning ヘルパーモジュールから showMultithreadingWarning をインポートします。この方法ではページのマークアップは不要です。React では、ヘルパーをインポートする代わりに、コンポーネントの状態を使って同じダイアログをレンダリングしてください。このダイアログはページの読み込みごとに最大 1 回だけ表示され、「このセッションでは再度表示しない」チェックボックスの設定に従います。COEP の credentialless はシングルスレッドでの実行を意味するものではありません。Safari はこれをサポートしていないため、Safari では引き続きダイアログが表示されます。

インテントに応じた参照先

ユーザーのリクエストに応じて、回答前に適切なリファレンスファイルを読み込んでください。複数のファイルが該当する場合もあります（例：React での統合で、カメラの問題も発生している場合）。関連するものをすべて読んでください。

• SparkScan を一から統合する（例：「アプリに SparkScan を追加したい」「バーコードスキャンを設定したい」「SparkScan の使い方を教えて」「SparkScan でフィードバックを処理する方法を教えて」「スキャンアプリを作りたい」）→ references/integration.md を読み、そこに記載された手順に従ってください。既存のプロジェクトがない場合は、まず用意済みのサンプルを案内するよう、ガイドから指示されます。
• プロジェクトで React を使用している（package.json に react 依存関係がある、.tsx／.jsx ファイルがある、フックや JSX を使っている）→ references/react.md も読んでください。<spark-scan-view> カスタム要素をバインドする正しい方法は React のメジャーバージョンによって異なるため、最初に package.json で react のバージョンを確認してください。ガイドでは React 18 と 19 の違い、およびコンテキストやライフサイクルに関する注意点を説明しています。React コードを書く前には必ず参照してください。一般的な integration.md の例は、バニラ TS です。
• 既存の SparkScan 統合を移行またはアップグレードする（例：「v6 から v7 にアップグレードしたい」「SparkScan を移行したい」「SDK のバージョン間で何が変わったか」）→ references/migration.md を読み、そこに記載された手順に従ってください。
• ランタイム、カメラ、デプロイに関する問題（例：「スマートフォンでカメラが起動しない」「一瞬動いた後に停止する」、クロスオリジン／COOP／COEP／ヘッダーの問題、「LAN IP でプレビューが真っ白になる」）→ references/troubleshooting.md を読んでください。これらは API の誤りではなく、環境やホスティングに関する問題であり、コードのバグと誤診されやすいものです。

API の使用ポリシー

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

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

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

URL の構造はさまざまです（例：api/ui/ サブディレクトリ）。推測すると 404 エラーにつながります。

ライセンスキー

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

以下の手順を順に実行してください。MCP を理由にユーザーを待たせないでください。

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

リファレンス

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

トピック	リソース
基本的な統合	Get Started · サンプル
React との統合	Get Started · サンプル
高度なトピック（カスタムフィードバック、ハードウェアトリガー、スキャンモード、UI のカスタマイズ）	Advanced Configurations
API リファレンス全体	SparkScan API