id-capture-rn

ID Capture React Native スキル

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

学習データには、古くなった、または誤った Scandit ID Capture API が含まれている可能性があります。ID Capture API は v7 から v8 への境界で再構成されました（scannerType プロパティは scanner に名称変更され、ラッパーとして再構成されました。単独の AamvaBarcodeVerifier は設定フラグに置き換えられ、複数の検証 API が追加されました）。React Native プラグインの表面仕様（パッケージ名、列挙型の大文字・小文字、ビューコンポーネント、AppState のライフサイクル）も、iOS、Android、Web、Flutter、Cordova、Capacitor の SDK とは異なります。

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

注意すべき React Native 固有のポイント：

• プラグインの初期化呼び出しはありません。 Flutter とは異なり、ScanditDataCaptureId.initialize() は呼び出しません。コアはインポート時に自動で初期化されます。「initialize」と呼ばれるのは DataCaptureContext.initialize(licenseKey) のみで、その後 DataCaptureContext.sharedInstance を使用するのが RN の規約です。
• 列挙型のメンバー名は PascalCase、ワイヤー値は camelCase です。 IdCaptureRegion.Us、IdImageType.CroppedDocument、IdSide.Front、RejectionReason.Timeout、IdAnonymizationMode.FieldsAndImages、IdFieldType.DocumentNumber、IdLayoutStyle.Rounded、FrameSourceState.On / .Off と記述してください。RN では小文字の Dart／Flutter 形式（IdCaptureRegion.us）は絶対に使用しないでください。
• CapturedId の MRZ／VIZ ゲッターは mrzResult / vizResult です（Flutter の mrz / viz ではありません）。その他、ソース固有のゲッターは barcode、mobileDocument、mobileDocumentOcr です。
• 画像は base64 文字列として返されます。 images.face、images.frame、images.getCroppedDocument(IdSide.Front)、images.getFrame(IdSide.Front) はそれぞれ string | null を返します。<Image source={{ uri: 'data:image/png;base64,' + face }} /> で表示してください。これらは URI、ファイル、Image コンポーネントではありません。
• リスナーはプレーンなオブジェクトリテラルです。 IdCaptureListener は省略可能なメソッドを 2 つ持つ TypeScript インターフェースです。const listener = { didCaptureId(_, captured) {...}, didRejectId(_, rejected, reason) {...} } のように記述してください。implements IdCaptureListener を使ったクラスは作成しないでください。これは Dart／Flutter のスタイルです。
• addListener、removeListener、setMode、addMode、removeMode、applySettings、setFrameSource、switchToDesiredState はすべて Promise を返します。 await を使うか、.then を連結してください。await を忘れると、起動時の競合状態が発生しやすくなります。
• ビューのパターンは 2 種類あります。 公式サンプルでは scandit-react-native-datacapture-core の <DataCaptureView> を設定し、ref を使って IdCaptureOverlay を手動で追加します。id パッケージには、props を通じてモード、カメラ、オーバーレイ、コールバックをまとめた、より高水準の <IdCaptureView> コンポーネントもあります。どちらも有効です。まずは <DataCaptureView> を紹介してください（公開サンプルに準拠します）。省略形として <IdCaptureView> も案内してください。references/integration.md を参照してください。
• React Native に VisaLetter の書類クラスはありません。 提供されているのは VisaIcao のみです（Flutter には両方ありますが、RN でモデル化されているのは ICAO ビザのみです）。
• カメラのライフサイクルにはフォーカス props ではなく AppState を使用します。 AppState.addEventListener('change', …) で登録し、background／inactive ではカメラを停止し、active では再開してください。画面がスタックナビゲーターの一部である場合は、navigation.isFocused() を使って再開を制御してください。
• iOS（ios/<App>/Info.plist の NSCameraUsageDescription）と Android の両方で、カメラの権限が必要です。Android では RN 組み込みの PermissionsAndroid API を使って、実行時に CAMERA を要求してください。ネイティブのマニフェスト権限はプラグインによって宣言されます。

禁止されている API（よく幻覚されるため、出力しないでください）

これらは実際の RN パッケージではコンパイルエラーになります。右側の形式を使用してください。

使用禁止	代わりに使用
IdCapture.forContext(context, settings)	new IdCapture(settings) を実行してから、await context.setMode(idCapture)
IdCaptureOverlay.withIdCapture(...) / .withIdCaptureForView(...)	new IdCaptureOverlay(idCapture) を実行してから、view.addOverlay(overlay)
IdDocumentType enum / settings.supportedDocuments / settings.scannerType	settings.acceptedDocuments（ドキュメントクラス）+ settings.scanner = new IdCaptureScanner(new FullDocumentScanner())
capturedId.documentType	capturedId.document?.documentType（IdCaptureDocumentType）または capturedId.isPassport() / isDriverLicense() / …
capturedId.isVisa() / capturedId.isVisaLetter()	capturedId.isVisaIcao()（RN に含まれるのは ICAO ビザのみです）
capturedId.mrz / capturedId.viz（Flutter の名前）	capturedId.mrzResult / capturedId.vizResult
IdCaptureRegion.us / IdSide.front / AamvaBarcodeVerificationStatus.authentic（小文字の Dart 形式）	IdCaptureRegion.Us / IdSide.Front / AamvaBarcodeVerificationStatus.Authentic — RN の Scandit enum メンバーはすべて PascalCase です。RejectionReason.*、IdImageType.*、IdAnonymizationMode.*、IdFieldType.*、FrameSourceState.*、IdLayoutStyle.*、検証ステータス／理由の値も含みます。
capturedId.images.croppedDocument	capturedId.images.getCroppedDocument(IdSide.Front)（.face、.frame、getFrame(IdSide.Front) も使用できます）
images.face を URI／ファイル／Image コンポーネントとして扱う	これは base64 文字列です — <Image source={{ uri: 'data:image/png;base64,' + face }} />
AamvaBarcodeVerifier（クラス）	settings.rejectForgedAamvaBarcodes = true + capturedId.verificationResult.aamvaBarcodeVerification
DrivingLicenseCategory.categoryCode	DrivingLicenseCategory.code（および dateOfIssue / dateOfExpiry）
idCapture.addListener(...) を await なしで実行（起動時に競合状態が発生します）	await idCapture.addListener(listener) — removeListener、setMode、applySettings、setFrameSource、switchToDesiredState も同様です

製品に関するガイダンス

ユーザーが API について質問しているときだけでなく、設計上の判断を行う際は常に以下のルールを適用してください。

• 実際に必要なドキュメントのみを受け付けてください。 acceptedDocuments を絞り込む（例：new DriverLicense(IdCaptureRegion.Us) のみ）と、すべてのドキュメントタイプを対象にする IdCaptureRegion.Any より高速かつ高精度になります。「すべて」をデフォルトにする前に、想定するドキュメントと地域をユーザーに確認してください。
• 必要なデータに合ったスキャナーを選んでください。 new FullDocumentScanner() は表面と裏面を自動的に読み取ります（ほとんどの ID／DL の用途に最適です）。new SingleSideScanner(barcode, machineReadableZone, visualInspectionZone) は有効にしたゾーンから片面を読み取ります。米国の DL の裏面にある PDF417 バーコードのみ、またはパスポートの MRZ のみが必要な場合に使用してください。モバイル運転免許証／mDL には MobileDocumentScanner を使用してください。
• didCaptureId だけでなく、didRejectId も処理してください。 拒否（RejectionReason.Timeout、NotAcceptedDocumentType、DocumentExpired、DocumentVoided、ForgedAamvaBarcode、…）によって、スキャンに失敗した理由がユーザーに伝わります。本番環境向けの統合では、ユーザーにメッセージを表示する必要があります。
• すべてのフィールドが不要な場合は、デフォルトで匿名化してください。 IdCaptureSettings.anonymizationMode とフィールド単位の addAnonymizedField を使うと、オプトインしない限り、規制対象データ（ドキュメント画像や機密フィールドなど）が結果に含まれないようにできます。ユースケースを満たす最小限の設定を推奨してください。
• ID Capture 以外の質問については、data-capture-sdk スキルに引き継いでください。 ユーザーが他の Scandit 製品（Barcode Capture、SparkScan、MatrixScan、Label Capture など）について、または製品の選択方法について尋ねた場合は、推測せずに data-capture-sdk スキルに引き継いでください。

意図に応じた参照先

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

• ID Capture を一から統合する（例：「RN アプリに ID スキャンを追加したい」「パスポート／運転免許証をスキャンする」「MRZ を読み取る」「所持者の名前と生年月日を抽出する」）→ references/integration.md を読み、その手順に従ってください。
• アドオン／高度な機能のいずれか（「無効／取り消し済みの ID を拒否する」「穴が開けられた／無効化された免許証を検出する」「欧州の運転免許証の裏面をデコードする」「車両カテゴリーを読み取る」「AAMVA バーコードを検証する／偽造された米国の免許証を検出する」「整合性のないデータを拒否する／データ整合性を検証する」「モバイル運転免許証／mDL／ISO 18013-5 モバイル文書をスキャンする」）→ references/supplementary-modules.md を読み込んでください。
• 既存の ID Capture 統合を移行またはアップグレードする（「ID Capture を最新の SDK にアップグレードする」「v7 から v8 に移行する」「scannerType のコードがコンパイルできなくなった」「AamvaBarcodeVerifier がなくなった」「バージョン間で ID Capture の何が変わったか」）→ references/migration.md を読み込んでください。
• React Navigation のルートライフサイクル、Expo／dev-client のセットアップ、SDK のハンドルの保持場所（「画面を離れてもカメラが止まらない」「フォーカス／ブラー時にカメラを一時停止する」「useFocusEffect」「Expo／Expo Go／Expo Router を使っている」「カスタム dev client は必要か」「expo-camera の権限」「IdCapture を Redux／Zustand に置くべきか」）→ references/framework-recipes.md を読み込んでください。Scandit のコード自体は references/integration.md から変更されていません。このファイルでは、React Navigation／Expo／状態管理に関する連携方法を説明しています。

API 利用ポリシー

以下の Scandit 参照資料で明示的に文書化されている API のみを使用してください。メソッドのシグネチャ、パラメーター、プロパティ名、インポートを創作したり、推測したりしないでください。API が存在するか、または呼び出し方がわからない場合、あるいは TypeScript コンパイラー／実行時にエラーが発生した場合は、回答する前に関連する参照ページを取得してください。ユーザー自身でドキュメントを確認するよう案内しないでください。回答後は、ユーザーがさらに詳しく確認できるよう、必ず関連リンクを含めてください。

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

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

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

フレームワーク別の方針

references/integration.md のサンプルでは、公式の IdCaptureSimpleSample がこの形式で記述されているため、関数コンポーネント＋React フック（useEffect、useRef、AppState）を使用しています。プロジェクトで React Navigation や Expo も使用している場合、または複数の画面間でコンテキストを共有したい場合は、references/framework-recipes.md を参照してください。Scandit の呼び出し方は変わりません。異なるのは、ナビゲーションのライフサイクル、Expo のビルドフロー、ref とストアの使い分けに関する指針のみです。ID Capture のためだけに新しい状態管理ライブラリを導入しないでください。

サンプルは TypeScript です（公式サンプルは .tsx です）。React Native >=0.74 を推奨します。

ライセンスキー

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

以下の手順を順に進めてください。MCP の利用を理由にユーザーを待たせないでください。

1. Scandit MCP サーバーが接続されている場合 — 製品に native、プラットフォームに ios と android、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 が返したキー、またはユーザーが貼り付けるか提供するキーです。チャットで表示するのは、引き続きマスクされたプレビューのみとしてください。プロジェクト、そのファイル、または環境内からキーを検索しないでください。

リファレンス

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

トピック	リソース
React Native の統合	はじめに · サンプル（IdCaptureSimpleSample）
高度なトピック（匿名化、検証、スキャナー、オーバーレイ）	高度な設定
SDK のメジャーバージョン間の移行	7 → 8
API リファレンス全体	ID Capture API