sparkscan-rn

SparkScan React Native スキル

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

学習データには、古い、または誤った Scandit SDK API が含まれている可能性があります。SparkScan API は SDK のメジャーバージョン間で大幅に変更されます。プロパティの名前が変更されたり、削除されたり、再構成されたりするほか、React Native プラグインの構成（インポート、ネイティブリンク、pod install、パッケージ名）も変化しています。

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

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

• DataCaptureContext.initialize(licenseKey) は、他の Scandit API を使用する前に必ず一度だけ呼び出してください。これにより DataCaptureContext.sharedInstance が設定され、ほかのすべての機能がこのシングルトンを参照します。コンテキストを複数作成しないでください。
• iOS では、Scandit パッケージをインストールまたはアップグレードするたびに npx [email protected]（または cd ios && pod install）を実行する必要があります。Android は Gradle によって自動リンクされるため、手動での作業は不要です。
• Metro のバンドラーキャッシュにより、Scandit パッケージのアップグレードが反映されないことがよくあります。プラグインのバージョンを上げた後に再ビルドしても古い動作が見られる場合は、Metro を --reset-cache 付きで起動してください。
• SparkScanView は子要素をラップする React コンポーネントです。ネイティブのスキャンコントロールは JSX ツリーに重ねて表示されます。子要素は、ネイティブのトリガーボタン、ツールバー、ミニプレビューの下に描画されます。SparkScanView をコンテンツと兄弟要素として描画しないでください。
• iOS（ios/<App>/Info.plist の NSCameraUsageDescription）と Android（PermissionsAndroid による実行時の許可リクエスト）の両方で、カメラの許可が必要です。プラグインがマニフェストの権限を自動で宣言します。

インテントの振り分け

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

• SparkScan を一から統合する（例：「アプリに SparkScan を追加する」「バーコードスキャンを設定する」「React Native で SparkScan を使う方法」「SparkScan でフィードバックを処理する方法」）→ references/integration.md を読み、そこに記載された手順に従ってください。
• 既存の SparkScan 統合を移行またはアップグレードする（例：「v6 から v7 にアップグレードする」「SparkScan を移行する」「Scandit パッケージを v8 に上げる」「SDK バージョン間で何が変わったか」）→ references/migration.md を読み、そこに記載された手順に従ってください。
• サードパーティ製スキャナーを SparkScan に置き換える（例：「expo-camera CameraView から SparkScan に移行する」「react-native-vision-camera の useCodeScanner / useBarcodeScannerOutput を Scandit に置き換える」「バーコードスキャナーライブラリを SparkScan に置き換える」）→ references/third-party-migration.md を読み、そこに記載された手順に従ってください。

API 使用ポリシー

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

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

1. まず、すでに取得したページ（例：Advanced Configurations ページ）に、そのページへの直接リンクが含まれているか確認してください。トピックページには関連する API シンボルへの直接リンクが記載されています。内容とあわせてリンクも取得するよう、必ずフェッチ時に指定してください。
2. 直接リンクが見つからない場合は、API インデックスを取得し（下の表の完全な API リファレンスを参照）、実際のリンクを抜き出してから、そのリンク先を開いてください。

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

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

React Native アプリは、クラスコンポーネントまたは関数コンポーネントで記述できます。このスキルの例では、公式の ListBuildingSample と現在の React Native の慣習に沿って、フックを使う関数コンポーネントを使用しています。対象プロジェクトのほかの部分にレガシーなクラスコンポーネントが残っていても、新しい SparkScan のコードは関数コンポーネントで記述してください。アプリのほかのコンポーネントのスタイルを書き換える必要はありませんが、SparkScan の統合部分自体は現在の慣用的な書き方（useRef、useEffect、useMemo、ビュー単位のプロパティには命令型の ref コールバック）にしてください。

例はTypeScript（.tsx）で記述されています。対象プロジェクトがプレーンな JavaScript（.js / .jsx）の場合は、型注釈を削除し、インポートと構造はそのままにしてください。

ライセンスキー

スキャンには 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 クライアントで https://ssl.scandit.com/mcp のリモート Scandit MCP サーバーに接続できることを、ユーザーに一度だけ伝えてから、手順 1 に進みます。MCP クライアントの設定は自分で編集しないでください。

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

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

その後、キーをコードに設定します：プレースホルダーの代わりに、ライセンスキー呼び出しへキーを記述してください。キーは、get_license_key が返したもの、またはユーザーが貼り付けたもの、あるいはユーザーから提供されたものです。チャット上では、マスクしたプレビューのみを表示してください。プロジェクト、そのファイル、または環境からキーを探してはいけません。

参考資料

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

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