id-capture-flutter

ID Capture Flutter スキル

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

学習データに、古くなった Scandit ID Capture API や誤った情報が含まれている可能性があります。ID Capture API は v7 から v8 への移行時に再構成されました（IdCaptureScanner は physicalDocumentScanner／mobileDocumentScanner をラップする形に変更され、単独の AamvaBarcodeVerifier は設定フラグに置き換えられ、複数の検証 API が追加されました）。Flutter プラグインの仕様（パッケージ名、プラグインの初期化、ウィジェットのライフサイクル）も、iOS、Android、Web、React Native、Cordova、Capacitor の SDK とは異なります。

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

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

• Scandit API を呼び出す前に、ID プラグインを初期化する必要があります。 main() 内で await ScanditFlutterDataCaptureId.initialize(); を呼び出してください（WidgetsFlutterBinding.ensureInitialized() の後、runApp の前）。ID プラグインを初期化するとコアプラグインも初期化されるため、コアの initialize() を別途呼び出す必要はありません。初期化を省略すると、原因の特定が困難なランタイム／MethodChannel クラッシュが発生します。
• Flutter での ID Capture では、DataCaptureContext.forLicenseKey(licenseKey) を使ってコンテキストを作成します（公式の IdCaptureSimpleSample と一致します）。DataCaptureContext.initialize(...) は使用しないでください。
• Flutter のリスナーメソッド名は iOS スタイルです： didCaptureId(IdCapture, CapturedId) と didRejectId(IdCapture, CapturedId?, RejectionReason) を使用します。Flutter には onIdCaptured や Web スタイルのコールバックはありません。
• 設定はビットマスクではなくリスト形式です。 settings.acceptedDocuments（必要に応じて settings.rejectedDocuments）にドキュメントオブジェクト（Passport(IdCaptureRegion.any)、DriverLicense(...)、IdCard(...) など）を設定し、settings.scanner を設定します。以前の supportedDocuments／IdDocumentType ビットマスク API は v6 から v7 への移行時点で削除されています。使用しないでください。また、スキャナープロパティは v7 から v8 への移行時に scannerType から scanner に名称変更され、ラッパー形式に再構成されました（references/migration.md を参照）。
• 3 つの機能追加モジュールは別々のパッケージですが、ベースモジュールの設定フラグで制御します（rejectVoidedIds、decodeBackOfEuropeanDrivingLicense、rejectForgedAamvaBarcodes）。references/supplementary-modules.md を参照してください。v8 の Flutter に単独の AamvaBarcodeVerifier クラスはありません。
• iOS（ios/Runner/Info.plist の NSCameraUsageDescription）と Android（プラグインにより宣言。実行時に permission_handler パッケージで要求）のどちらでも、カメラ権限が必要です。

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

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

記述しない	代わりに使用
IdCapture.forContext(context, settings)	IdCapture(settings) の後に context.setMode(idCapture)
IdCaptureOverlay.withIdCapture(...) / .withIdCaptureForView(...)	IdCaptureOverlay(idCapture) の後に captureView.addOverlay(overlay)
IdDocumentType enum / settings.supportedDocuments / settings.scannerType	settings.acceptedDocuments（ドキュメントクラス）+ settings.scanner = IdCaptureScanner(physicalDocumentScanner: ...)
capturedId.documentType	capturedId.document?.documentType（IdCaptureDocumentType）または capturedId.isPassport() / isDriverLicense() / …
capturedId.isVisa()	capturedId.isVisaIcao() / capturedId.isVisaLetter()
capturedId.images.croppedDocument	capturedId.images.getCroppedDocument(IdSide.front)（.face、.frame、getFrame(IdSide.front) も使用できます）
IdImages の結果に対する image.buffer / image.bytes / Image.memory(image…)	結果はすでに Flutter の Image ウィジェットです。ウィジェットツリーに直接レンダリングしてください
AamvaBarcodeVerifier（クラス）	settings.rejectForgedAamvaBarcodes = true + capturedId.verificationResult.aamvaBarcodeVerification
DrivingLicenseCategory.categoryCode	DrivingLicenseCategory.code（および dateOfIssue / dateOfExpiry）

• DataCaptureView は Flutter ウィジェットであり、そのライフサイクルはウィジェットツリーに紐づいています。画面を離れる際は、didChangeAppLifecycleState（WidgetsBindingObserver 経由）でカメラを一時停止し、リスナーをクリーンアップしてモードを無効にしてください。

製品に関するガイダンス

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

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

意図の振り分け

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

• ID Capture をゼロから統合する（例：「アプリに ID スキャンを追加したい」「パスポート／運転免許証をスキャンしたい」「MRZ を読み取りたい」「所持者の氏名と生年月日を抽出したい」）→ references/integration.md を読み、その手順に従ってください。
• 3 つのアドオン機能のいずれか（「無効化／キャンセル済みの ID を拒否する」「穴が開けられた／無効化された免許証を検出する」「欧州の運転免許証の裏面をデコードする」「車両カテゴリーを読み取る」「AAMVA バーコードを検証する／偽造された米国の免許証を検出する」）、または データ整合性の検証（「印字されたデータが MRZ／バーコードと一致しない書類を拒否する」「改ざんされた ID を検出する」「VIZ とバーコードを照合する」）→ references/supplementary-modules.md を読み込んでください。
• 既存の ID Capture 統合を移行またはアップグレードする（「ID Capture を最新の SDK にアップグレードしたい」「v7 から v8 に移行したい」「supportedDocuments のコードがコンパイルできなくなった」「AamvaBarcodeVerifier がなくなった」「バージョン間で ID Capture にどのような変更があったか」）→ references/migration.md を読み込んでください。
• 状態管理またはルートのライフサイクル（「BLoC でこれを実現するには？」「Riverpod／AsyncNotifier のセットアップ」「別の画面に遷移してもカメラが一時停止しない」「RouteAware／RouteObserver」「GoRouter と ID Capture」「IdCapture を Provider／ChangeNotifier に保持すべきか？」）→ references/framework-recipes.md を読み込んでください。Scandit のコード自体は references/integration.md から変更されていません。このファイルでは、BLoC／Riverpod／ルートオブザーバーとの連携について説明します。

API 使用ポリシー

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

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

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

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

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

references/integration.md の例では、公式の IdCaptureSimpleSample で使用されている StatefulWidget + WidgetsBindingObserver を使います。プロジェクトで BLoC（IdCaptureExtendedSample と同様）、Riverpod、またはルートオブザーバー／GoRouter を使用している場合は、references/framework-recipes.md を参照してください。Scandit の呼び出し方は変わりません。異なるのは状態管理の仕組みと、ルートに応じたライフサイクルです。ID Capture のためだけに新しい状態管理ライブラリを導入しないでください。

例は Dart（サウンドな null 安全性）です。ID プラグインには Flutter >=3.22.0 と Dart >=3.4.0 が必要です。

ライセンスキー

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

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

1. Scandit MCP サーバーが接続されている場合 — 製品に native、プラットフォームに ios と android を指定して ensure_scanner_setup を呼び出し、続いて get_license_env_command が返すコマンドを実行して、キーをプロジェクトの .env に書き込みます。チャットに表示するのはマスキングしたプレビューまでとし、キー全体を表示しないでください。

2. 接続されていない場合 — 一度接続するかユーザーに確認し、ステップ 1 に進みます。

   • Claude Code：claude mcp add --transport http scandit https://ssl.scandit.com/mcp
   • Cursor：{"mcpServers": {"scandit": {"url": "https://ssl.scandit.com/mcp"}}} を ~/.cursor/mcp.json に追加します
   • VS Code：{"servers": {"scandit": {"type": "http", "url": "https://ssl.scandit.com/mcp"}}} を MCP のユーザー設定に追加します

   認証はブラウザー経由のため、ヘッドレス環境や CI ではサポートされていません。サーバーが発行するのは試用版のキーのみです。本番ライセンスの作成、取り消し、変更は行いません。

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

その後、プレースホルダーをキーに置き換えてコードに設定します。.env にキーを記述しただけでは、アプリには反映されません。ビルド時に --dart-define-from-file=.env で渡し、String.fromEnvironment で読み取ります。どのプラットフォームでも最も簡単なのは、.env を読み込んでライセンスキー呼び出しに直接キーを指定する方法です。この場合も、チャットにはマスキングしたプレビューのみを表示してください。

参考資料

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

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