id-capture-capacitor

ID Capture Capacitor スキル

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

学習データに、古い Scandit ID Capture API や誤った情報が含まれている可能性があります。ID Capture API は v7 → v8 の境目で再構成されました（scannerType プロパティは名前が scanner に変更され、ラッパーとして再構成されました。単独の AamvaBarcodeVerifier は削除され、代わりに設定フラグが使われるようになり、複数の検証 API が追加されました）。また、Capacitor プラグインの仕様（パッケージ名、命令型の DataCaptureView と connectToElement のパターン、明示的な起動時の initializePlugins()）は、iOS、Android、Web、Flutter、React Native、Cordova の SDK とは異なります。

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

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

• プラグインの明示的な初期化が必要です。 Capacitor は自動初期化しません。アプリの起動時に、DataCaptureContext などを作成する前に、await ScanditCaptureCorePlugin.initializePlugins() を一度呼び出してください。呼び出さないとネイティブブリッジが接続されず、原因の分かりにくい「plugin not implemented」エラーが発生します。
• ビューは <div> に接続する命令型クラスであり、カスタム要素ではありません。 <data-capture-view> という HTML タグはなく、Scandit が提供する React／Vue／Angular コンポーネントもありません。DataCaptureView.forContext(context) でビューを作成し、view.connectToElement(divElement) で通常の <div id="..."> に接続してください。別の画面に遷移するときは、view.detachFromElement() で切り離します。
• DataCaptureContext.initialize(licenseKey) はコンテキストを返します。 戻り値を取得してください。例：const context = DataCaptureContext.initialize('<key>');。このサンプルでは sharedInstance パターンを使いません。返されたコンテキストへの参照を保持してください。
• カメラは Camera.default + applySettings ではなく、Camera.withSettings(...) で構築します。 ID Capture 用に事前設定されたカメラを構築するには、Camera.withSettings(IdCapture.createRecommendedCameraSettings()) を使用してください。Flutter／RN 形式の Camera.default は、Capacitor サンプルの書き方とは異なります。
• 列挙型のメンバー名は PascalCase、ワイヤー値は camelCase です（RN と同じ TypeScript の規則です）。IdCaptureRegion.Us、IdImageType.CroppedDocument、IdSide.Front、RejectionReason.Timeout、IdAnonymizationMode.FieldsAndImages、IdFieldType.DocumentNumber、IdLayoutStyle.Rounded、FrameSourceState.On／.Off、AamvaBarcodeVerificationStatus.Authentic のように記述してください。Dart／Flutter の小文字形式は決して使用しないでください。
• 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 を返します。<img src="data:image/png;base64,${face}"> で表示するか（または既存の <img> の .src に設定してください）。URI、ファイル、HTMLImageElement ではありません。
• リスナーは通常のオブジェクトリテラルです。 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 をチェーンしてください。
• Capacitor には VisaLetter ドキュメントクラスはありません。 提供されているのは VisaIcao のみです。（Flutter には両方ありますが、Capacitor／RN では ICAO ビザのみがモデル化されています。）
• ライフサイクルには AppState（RN）や WidgetsBindingObserver（Flutter）ではなく、Capacitor の App プラグイン（@capacitor/app）を使用します。 App.addListener('appStateChange', …) でイベントを購読し、カメラを一時停止／再開して、モードを無効にしてください。
• カメラの権限は @capacitor/camera プラグインで処理します。プラグインをインストールし、iOS の Info.plist に NSCameraUsageDescription を追加してください。スキャンビューをマウントする前に、Scandit の Camera クラスとは別の @capacitor/camera から Camera.requestPermissions() を呼び出します。

禁止されている API（よく幻覚されます。出力しないでください）

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

記述しない	代わりに使用
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()（Capacitor に含まれるビザは ICAO ビザのみです）
capturedId.mrz / capturedId.viz（Flutter の名称）	capturedId.mrzResult / capturedId.vizResult
IdCaptureRegion.us / IdSide.front / AamvaBarcodeVerificationStatus.authentic（小文字の Dart 形式）	IdCaptureRegion.Us / IdSide.Front / AamvaBarcodeVerificationStatus.Authentic — Capacitor の Scandit の列挙型メンバーはすべて PascalCase です。RejectionReason.*、IdImageType.*、IdAnonymizationMode.*、IdFieldType.*、FrameSourceState.*、IdLayoutStyle.*、検証ステータス／理由も含まれます
capturedId.images.croppedDocument	capturedId.images.getCroppedDocument(IdSide.Front)（.face、.frame、getFrame(IdSide.Front) も使用できます）
images.face を URI／ファイル／HTMLImageElement のように扱う	base64 文字列です。<img src="data:image/png;base64,${face}"> または imgEl.src = '...' を使用します
AamvaBarcodeVerifier（クラス）	settings.rejectForgedAamvaBarcodes = true + capturedId.verificationResult.aamvaBarcodeVerification
DrivingLicenseCategory.categoryCode	DrivingLicenseCategory.code（および dateOfIssue / dateOfExpiry）
<data-capture-view> カスタム要素または <IdCaptureView> React 形式のコンポーネント	DataCaptureView.forContext(context) + view.connectToElement(document.getElementById('...'))
Camera.default（RN／Flutter の慣用表現）	Camera.withSettings(IdCapture.createRecommendedCameraSettings())
起動時に ScanditCaptureCorePlugin.initializePlugins() を省略する	他の Scandit API を呼び出す前に、必ず await ScanditCaptureCorePlugin.initializePlugins(); を実行します
起動時の競合を招く、await なしの idCapture.addListener(...)	await idCapture.addListener(listener) を使用します。removeListener、setMode、applySettings、setFrameSource、switchToDesiredState も同様です

製品に関するガイダンス

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

• 実際に必要なドキュメントだけを受け付けます。 範囲を絞ったacceptedDocumentsリスト（例：new DriverLicense(IdCaptureRegion.Us)のみ）は、すべてのドキュメントタイプを対象とするIdCaptureRegion.Anyよりも高速で、精度も高くなります。「すべて」をデフォルトにする前に、ユーザーが想定しているドキュメントと地域を確認してください。
• 必要なデータに合ったスキャナーを選びます。 new FullDocumentScanner()は表面と裏面を自動的に読み取ります（ほとんどのID／運転免許証のユースケースに最適です）。new SingleSideScanner(barcode, machineReadableZone, visualInspectionZone)は、有効にしたゾーンから片面を読み取ります。たとえば、米国の運転免許証の裏面にある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を一から導入する（例：「CapacitorアプリにIDスキャンを追加したい」「パスポート／運転免許証をスキャンしたい」「MRZを読み取りたい」「所持者の氏名と生年月日を抽出したい」）→ references/integration.mdを読み、記載内容に従ってください。
• 3つのアドオン機能のいずれかを利用する（「無効／取り消し済みのIDを拒否する」「穴が開いた／無効化された免許証を検出する」「欧州運転免許証の裏面をデコードする」「車両カテゴリを読み取る」「AAMVAバーコードを検証する／偽造された米国の免許証を検出する」）→ references/supplementary-modules.mdを読みます。
• 既存のID Captureインテグレーションを移行またはアップグレードする（「ID Captureを最新のSDKにアップグレードしたい」「v7からv8に移行したい」「scannerTypeのコードがコンパイルできなくなった」「AamvaBarcodeVerifierがなくなった」「バージョン間でID Captureに何が変更されたか」）→ references/migration.mdを読みます。
• Capacitor上のホストUIフレームワークにID Captureを組み込む（「Ionic Angularではどうすればよいですか？」「Ionic Reactのライフサイクルを見せてください」「Vue 3／Composition APIを使っています」「ngAfterViewInit／useEffect／onMountedでカメラの開始／停止処理をどこに記述すればよいですか？」「ルート遷移時のページライフサイクル」「data-capture-viewのdivに対する@ViewChild」）→ references/framework-recipes.mdを読みます。Scanditのコード自体はreferences/integration.mdから変更されていません。このファイルでは、各フレームワークに応じたライフサイクルの連携部分だけを説明しています。

API 使用ポリシー

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

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

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

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

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

references/integration.md の例は TypeScript／プレーンな JS（フレームワーク固有のバインディングなし）です。公式の IdCaptureSimpleSample は、DOMContentLoaded の後に実行される JS で記述されています。対象プロジェクトが Capacitor の上に構築されたフレームワーク（Ionic Angular、Ionic React、Vue 3）を使用している場合は、ライフサイクルのひな型について references/framework-recipes.md を参照してください。Scandit の呼び出し方は変わりません。異なるのは呼び出しを組み込む場所だけです。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 クライアントでリモート 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 が返したもの、またはユーザーが貼り付けた、もしくは伝えたものを使用します。チャットでは引き続きマスクしたプレビューのみを表示してください。プロジェクト、ファイル、環境からキーを検索してはいけません。

参考資料

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

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