matrixscan-ar-rn

MatrixScan AR React Native スキル

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

学習データには、古くなった Scandit SDK API や誤った情報が含まれている可能性があります。BarcodeAr* 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 を付けて起動してください。
• BarcodeArView は子要素をラップする React コンポーネントです。ネイティブ AR オーバーレイは JSX ツリーの上に描画されます。子要素はネイティブ AR レイヤーの下に描画されます。オーバーレイの下に表示したいコンテンツと兄弟要素として BarcodeArView を描画しないでください。
• ハイライトプロバイダー（BarcodeArHighlightProvider.highlightForBarcode）とアノテーションプロバイダー（BarcodeArAnnotationProvider.annotationForBarcode）は、バーコードごとに一度、非同期で呼び出されます。これらは、ハイライトまたはアノテーションオブジェクトに解決される Promise を返す async 関数です。同期的に値が返ると想定しないでください。
• BarcodeArView は、ref コールバック内で view.start() を明示的に呼び出して開始する必要があります。SparkScan とは異なり、マウント時にビューが自動で開始されることはありません。
• iOS（ios/<App>/Info.plist の NSCameraUsageDescription）と Android（PermissionsAndroid による実行時のリクエスト）の両方で、カメラの権限が必要です。プラグインは Android のマニフェスト権限を自動で宣言します。
• BarcodeAr には SDK 7.1 以降が必要です。コンテキスト引数を指定しない new BarcodeAr(settings) コンストラクターは、react-native=7.6 以降で使用できます。dataCaptureContext.addMode(barcodeAr) を使用してモードをコンテキストに追加してください。
• BarcodeArCustomHighlight には SDK 8.0 以降が必要です。BarcodeArCustomAnnotation には SDK 8.1 以降、BarcodeArResponsiveAnnotation には SDK 8.2 以降が必要です。

インテントの振り分け

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

• MatrixScan AR を一から統合する（例：「アプリに MatrixScan AR を追加する」「Barcode AR を設定する」「React Native で BarcodeArView を使う方法」「バーコードに AR オーバーレイを表示する方法」「ハイライトやアノテーションを追加または変更する」「ライフサイクル、クリーンアップ、セッション処理」）→ references/integration.md を読み、そこに記載された手順に従ってください。
• BarcodeBatch から BarcodeAr に移行する（例：「BarcodeBatch から移行する」「BarcodeBatch を BarcodeAr に変換する」「MatrixScan から MatrixScan AR に移行する」「BarcodeTracking を BarcodeAr に置き換える」「古い MatrixScan コードを AR にアップグレードする」）→ references/migration.md を読み、そこに記載された手順に従ってください。

API の使用ポリシー

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

ドキュメントの URL を組み立てたり、推測したりしてはいけません。 特定のクラスやプロパティの API ページが必要な場合は、次の手順に従ってください。

1. まず、すでに取得したページに該当ページへの直接リンクがあるか確認してください。トピックページから関連する API シンボルに直接リンクされている場合があります。取得を依頼するときは、必ずコンテンツとともにリンクも含めるようにしてください。
2. 直接リンクが見つからない場合は、API インデックスを取得し（以下の表の完全な API リファレンスを参照）、そこから実際のリンクを抽出してアクセスしてください。

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

フレームワークのバリアントに関するポリシー

React Native アプリは、クラスコンポーネントまたは関数コンポーネントで記述できます。このスキルの例では、現在の React Native の慣習に沿ったフックを使う関数コンポーネントを使用します。対象プロジェクトにレガシーなクラスコンポーネントが残っていても、新しい MatrixScan AR コードは関数コンポーネントで記述してください。アプリのほかの部分のコンポーネントスタイルを書き換える必要はありませんが、BarcodeAr* の統合部分は現在の慣用的な書き方（useRef、useEffect、useMemo）にしてください。

例は 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 クライアントでリモート 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 が返したもの、またはユーザーが貼り付けるか伝えたものを使用し、チャットでは引き続きマスクしたプレビューのみを表示してください。プロジェクト、そのファイル、環境内からキーを検索してはいけません。

リファレンス

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

トピック	リソース
React Native の統合	はじめに
完全な API リファレンス	BarcodeAr API