id-capture-cordova

ID Capture Cordova スキル

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

学習データに、古くなった、または誤った Scandit ID Capture API が含まれている可能性があります。ID Capture API は v7 から v8 への移行時に再構成されました（単独の AamvaBarcodeVerifier は削除され、設定フラグに置き換えられ、複数の検証 API が追加されました）。Cordova プラグインのインターフェース（deviceready 後のグローバルな Scandit.* 名前空間、命令型の DataCaptureView と connectToElement のパターン、ドキュメントイベントの pause／resume）も、iOS、Android、ウェブ、Flutter、React Native、Capacitor の各 SDK とは異なります。

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

Cordova 固有の注意点として、必ず明示しておくべきものは以下のとおりです。

• Scandit API にアクセスする前に、必ず deviceready を待ってください。 Cordova プラグインシステムは、deviceready イベントに応じて window.Scandit.* を設定し、ネイティブブリッジを登録します。モジュールの読み込み時に Scandit.DataCaptureContext.initialize(...)（またはその他の処理）を呼び出すと、シンボルが undefined になります。ブートストラップ処理は必ず document.addEventListener('deviceready', () => { … }, false); で囲んでください。
• 利用するのは import ではなく、Scandit.* グローバルです。 Cordova のプラグインローダーは、すべての Scandit クラスを window.Scandit に統合します。new Scandit.IdCapture(settings)、Scandit.IdCaptureRegion.Us、Scandit.RejectionReason.Timeout のように記述してください。アプリケーションコードで import { IdCapture } from 'scandit-cordova-datacapture-id' を記述することはありません（このパスは、プラグイン独自の TypeScript ビルド内でのみ解決されます）。
• ビューは <div> に接続する命令型クラスであり、カスタム要素ではありません。 <data-capture-view> という HTML タグはありません。Scandit.DataCaptureView.forContext(context) でビューを作成し、view.connectToElement(divElement) で通常の <div id="…"> に接続します。画面遷移時には view.detachFromElement() で切り離してください。
• Scandit.DataCaptureContext.initialize(licenseKey) はコンテキストを返します。 戻り値を取得してください：const context = Scandit.DataCaptureContext.initialize('<key>');。Cordova のサンプルに sharedInstance パターンはありません。
• カメラは Scandit.Camera.withSettings(...) で構築し、戻り値は Camera | null です。 Scandit.Camera.withSettings(Scandit.IdCapture.createRecommendedCameraSettings()) を使用し、参照する前に戻り値が null でないことを確認してください。
• 列挙型のメンバー名は PascalCase で、ワイヤー値は camelCase です（RN／Capacitor と同じ TypeScript の規則です）。Scandit.IdCaptureRegion.Us、Scandit.IdImageType.CroppedDocument、Scandit.IdSide.Front、Scandit.RejectionReason.Timeout、Scandit.IdAnonymizationMode.FieldsAndImages、Scandit.IdFieldType.DocumentNumber、Scandit.IdLayoutStyle.Rounded、Scandit.FrameSourceState.On／.Off、Scandit.AamvaBarcodeVerificationStatus.Authentic のように記述してください。Dart／Flutter の小文字形式は使用しないでください。
• CapturedId の MRZ／VIZ ゲッターは mrzResult／vizResult です（Flutter のような mrz／viz ではありません）。その他のソース固有のゲッター：barcode、mobileDocument、mobileDocumentOcr。
• 画像は base64 文字列として返されます。 images.face、images.frame、images.getCroppedDocument(Scandit.IdSide.Front)、images.getFrame(Scandit.IdSide.Front) は、それぞれ string | null を返します。<img src="data:image/png;base64,${face}"> のように表示してください。URI、ファイル、HTMLImageElement ではありません。
• リスナーは通常のオブジェクトリテラルです。 Scandit.IdCaptureListener は、2 つの省略可能なメソッドを持つ TypeScript インターフェースです。const listener = { didCaptureId(_, captured) { … }, didRejectId(_, rejected, reason) { … } } のように記述してください。implements IdCaptureListener を指定したクラスは作成しないでください。これは Dart／Flutter のスタイルです。
• Cordova に VisaLetter ドキュメントクラスはありません。 提供されているのは VisaIcao のみです。（Flutter には両方ありますが、Cordova／RN／Capacitor では ICAO ビザのみがモデル化されています。）
• ライフサイクルには Cordova の pause／resume ドキュメントイベントを使用します。 document.addEventListener('pause' / 'resume', …) で登録し、カメラを停止／再起動し、idCapture.isEnabled を切り替えてください。React の AppState（RN のもの）も、@capacitor/app プラグイン（Capacitor のもの）もありません。
• カメラの権限はプラグインによって宣言され、ネイティブ側で処理されます。Cordova ID プラグインには JavaScript 側で権限をリクエストする機能はありません。プロンプトを表示するタイミングを制御したい場合は、cordova-plugin-android-permissions をインストールするか、プロジェクトで既に使用している権限プラグインのカメラ権限 API を呼び出し、スキャンビューをマウントする前に CAMERA をリクエストしてください。そうしない場合、カメラの初回使用時に OS がプロンプトを表示します。

禁止されている API（よく幻覚されるもの — 出力しないでください）

これらは存在しないか、削除されています。右側の形式を使用してください。

使用しないでください	代わりに使用してください
アプリケーションコード内の import { IdCapture } from 'scandit-cordova-datacapture-id'	deviceready の後に new Scandit.IdCapture(settings)（Cordova はシンボルを window.Scandit にマージします）
Scandit.IdCapture.forContext(context, settings)	new Scandit.IdCapture(settings) の後に context.setMode(idCapture)
Scandit.IdCaptureOverlay.withIdCapture(...) / .withIdCaptureForView(...)	new Scandit.IdCaptureOverlay(idCapture) の後に view.addOverlay(overlay)
IdDocumentType enum / settings.supportedDocuments	settings.acceptedDocuments（ドキュメントクラス）と settings.scanner = new Scandit.IdCaptureScanner(new Scandit.FullDocumentScanner())
capturedId.documentType	capturedId.document?.documentType（IdCaptureDocumentType）または capturedId.isPassport() / isDriverLicense() / …
capturedId.isVisa() / capturedId.isVisaLetter()	capturedId.isVisaIcao()（Cordova で提供されるのは ICAO ビザのみです）
capturedId.mrz / capturedId.viz（Flutter の名称）	capturedId.mrzResult / capturedId.vizResult
Scandit.IdCaptureRegion.us / Scandit.IdSide.front / Scandit.AamvaBarcodeVerificationStatus.authentic（小文字の Dart 形式）	Scandit.IdCaptureRegion.Us / Scandit.IdSide.Front / Scandit.AamvaBarcodeVerificationStatus.Authentic — Cordova の Scandit enum メンバーはすべて PascalCase です。RejectionReason.*、IdImageType.*、IdAnonymizationMode.*、IdFieldType.*、FrameSourceState.*、IdLayoutStyle.*、および検証ステータス／理由も含まれます
capturedId.images.croppedDocument	capturedId.images.getCroppedDocument(Scandit.IdSide.Front)（.face、.frame、getFrame(Scandit.IdSide.Front) も使用できます）
images.face を URI／ファイル／HTMLImageElement のように扱うこと	これは base64 文字列です — <img src="data:image/png;base64,${face}"> または imgEl.src = '...'
Scandit.AamvaBarcodeVerifier（クラス）	settings.rejectForgedAamvaBarcodes = true と capturedId.verificationResult.aamvaBarcodeVerification
DrivingLicenseCategory.categoryCode	DrivingLicenseCategory.code（および dateOfIssue / dateOfExpiry）
<data-capture-view> カスタム要素またはあらゆるフレームワークコンポーネントラッパー	Scandit.DataCaptureView.forContext(context) と view.connectToElement(document.getElementById('...'))
Camera.default（RN／Flutter の慣用形式）	Scandit.Camera.withSettings(Scandit.IdCapture.createRecommendedCameraSettings()) — 戻り値の Camera | null を必ずガードしてください
deviceready が発火する前に Scandit.* にアクセスすること	ブートストラップ処理を document.addEventListener('deviceready', () => { … }, false); で囲んでください

製品選定の指針

ユーザーが設計上の判断をしている場合は、API に関する質問だけでなく、常に次のルールを適用してください。

• 本当に必要なドキュメントだけを受け入れてください。 範囲を絞った acceptedDocuments リスト（例：new Scandit.DriverLicense(Scandit.IdCaptureRegion.Us) のみ）のほうが、すべてのドキュメントタイプを対象とする IdCaptureRegion.Any よりも高速で正確です。「すべて」をデフォルトにする前に、ユーザーが想定しているドキュメントと地域を尋ねてください。
• 必要なデータに合ったスキャナーを選んでください。 new Scandit.FullDocumentScanner() は表裏を自動的に読み取ります（ほとんどの ID／運転免許証のユースケースに最適です）。new Scandit.SingleSideScanner(barcode, machineReadableZone, visualInspectionZone) は、有効にしたゾーンから片面を読み取ります。モバイル運転免許証／mDL には Scandit.MobileDocumentScanner を使用してください。
• didCaptureId だけでなく、didRejectId も処理してください。 拒否（Scandit.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 を最初から統合する（「Cordova アプリに ID スキャンを追加する」、「パスポート／運転免許証をスキャンする」、「MRZ を読み取る」、「所持者の氏名と生年月日を抽出する」）→ references/integration.md を読み、その手順に従ってください。
• 3 つの追加機能のいずれか（「無効／取り消し済みの ID を拒否する」、「パンチ穴のある／無効化された免許証を検出する」、「欧州の運転免許証の裏面をデコードする」、「車両カテゴリーを読み取る」、「AAMVA バーコードを検証する／偽造された米国の免許証を検出する」）→ references/supplementary-modules.md を読みます。
• 既存の ID Capture 統合を移行またはアップグレードする（「ID Capture を最新の SDK にアップグレードする」、「v7 から v8 に移行する」、「AamvaBarcodeVerifier がなくなった」、「バージョン間で ID Capture にどのような変更があったか」）→ references/migration.md を読みます。

API 使用ポリシー

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

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

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

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

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

このスキルの例では、プレーンな JavaScript / TypeScript（UI フレームワークのバインディングなし）を使用します。公式の IdCaptureSimpleSample は、deviceready の後に実行されるプレーンな www/js/*.js だからです。Cordova 上で UI フレームワーク（jQuery Mobile、Onsen UI、古い Ionic v1 / Ionic v3 のセットアップ、Framework7）を使用している場合は、同じブートストラップと Scandit の呼び出しを維持し、フレームワークのビューテンプレート内にあるホスト <div> に view.connectToElement(...) を接続してください。ID Capture のためだけに新しいフレームワークを導入しないでください。

ライセンスキー

スキャンには 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 が返したもの、またはユーザーが貼り付けたものや提示したものを使います。チャットでは引き続き、マスクしたプレビューのみを表示してください。キーを探すためにプロジェクト、プロジェクトのファイル、環境を検索しないでください。

参考資料

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

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