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 注意事项：

• 必须先初始化 ID 插件，才能调用任何 Scandit API。 在 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 风格的回调。
• 设置采用列表，而非位掩码。 使用文档对象（Passport(IdCaptureRegion.any)、DriverLicense(...)、IdCard(...) 等）配置 settings.acceptedDocuments（也可以配置 settings.rejectedDocuments），并设置 settings.scanner。旧的 supportedDocuments / IdDocumentType 位掩码 API 已在 v6 → v7 的版本边界处移除——不要使用。另请注意，扫描器属性在 v7 → v8 期间从 scannerType 重命名为 scanner，并改造成了包装器（见 references/migration.md）。
• 三个能力附加模块是独立的包，但由基础模块的设置标志驱动（rejectVoidedIds、decodeBackOfEuropeanDrivingLicense、rejectForgedAamvaBarcodes）。见 references/supplementary-modules.md。Flutter v8 中没有独立的 AamvaBarcodeVerifier 类。
• iOS（ios/Runner/Info.plist 中的 NSCameraUsageDescription）和 Android 都需要相机权限（插件会声明权限；运行时请使用 permission_handler 包请求权限）。

禁止使用的 API（常见幻觉——切勿输出）

这些写法无法通过真实 Flutter 软件包的编译。请使用右侧的写法：

不要写	改用
IdCapture.forContext(context, settings)	IdCapture(settings)，然后调用 context.setMode(idCapture)
IdCaptureOverlay.withIdCapture(...) / .withIdCaptureForView(...)	IdCaptureOverlay(idCapture)，然后调用 captureView.addOverlay(overlay)
IdDocumentType 枚举 / 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 widget，直接在组件树中渲染即可
AamvaBarcodeVerifier（类）	settings.rejectForgedAamvaBarcodes = true + capturedId.verificationResult.aamvaBarcodeVerification
DrivingLicenseCategory.categoryCode	DrivingLicenseCategory.code（以及 dateOfIssue / dateOfExpiry）

• DataCaptureView 是一个 Flutter widget，其生命周期与 widget 树绑定。离开屏幕时，请在 didChangeAppLifecycleState 中暂停相机（通过 WidgetsBindingObserver），并清理监听器 / 禁用模式。

产品指南

每当用户需要做出设计决策时，都应遵循以下规则，而不只是回答 API 问题。

• 只接受你实际需要的证件。 范围较窄的 acceptedDocuments 列表（例如仅包含 DriverLicense(IdCaptureRegion.us)）比对所有证件类型使用 IdCaptureRegion.any 更快、更准确。在默认选择“全部”之前，先询问用户预期支持哪些证件和地区。
• 选择与所需数据相匹配的扫描器。 FullDocumentScanner() 会自动读取正反面，适合大多数身份证件 / 驾照场景。SingleSideScanner(barcode, machineReadableZone, visualInspectionZone) 会读取启用区域中的单面；如果你只需要美国驾照背面的 PDF417 条码，或只需要护照的 MRZ，就应使用它。对于移动驾照 / mDL，请使用 MobileDocumentScanner。
• 处理 didRejectId，不要只处理 didCaptureId。 拒绝原因（RejectionReason.timeout、notAcceptedDocumentType、documentExpired、documentVoided、forgedAamvaBarcode、…）可以告知用户扫描未成功的原因。生产环境集成必须向用户显示相关提示。
• 默认匿名化不需要的字段。 IdCaptureSettings.anonymizationMode 和逐字段匿名化功能可以确保受监管的数据（例如证件图像、敏感字段）不会出现在结果中，除非你选择将其纳入结果。建议仅保留满足使用场景所需的最少信息。
• 非 ID-Capture 问题请转交给 data-capture-sdk skill。 如果用户询问其他 Scandit 产品（Barcode Capture、SparkScan、MatrixScan、Label Capture 等），或询问如何在产品之间进行选择，请转交给 data-capture-sdk skill，而不要猜测。

意图路由

根据用户的请求，在回复前加载相应的参考文件：

• 从零开始集成 ID Capture（例如“在我的应用中添加 ID 扫描”“扫描护照／驾驶证”“读取 MRZ”“提取持有人的姓名和出生日期”）→ 阅读 references/integration.md 并遵循其中的说明。
• 三种附加功能之一（“拒绝已作废／已取消的证件”“检测有冲孔／已作废的驾驶证”“解码欧洲驾驶证背面的信息”“读取车辆类别”“验证 AAMVA 条码／检测伪造的美国驾驶证”）或 数据一致性验证（“拒绝印刷数据与 MRZ／条码不匹配的证件”“检测遭篡改的证件”“交叉核对 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 版本和包路径而异，猜测 URL 会导致 404 错误。

框架变体政策

references/integration.md 中的示例使用 StatefulWidget + WidgetsBindingObserver，因为官方的 IdCaptureSimpleSample 采用了这种方式。如果项目使用 BLoC（与 IdCaptureExtendedSample 一致）、Riverpod 或路由观察器／GoRouter，请参阅 references/framework-recipes.md——Scandit 调用方式不变；变化的只有状态管理框架和路由感知生命周期。不要仅为了 ID Capture 引入新的状态管理库。

示例使用 Dart（健全的空安全）。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