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、web、Flutter、React Native 和 Capacitor SDK。

编写或建议代码前，务必根据本技能提供的参考资料验证 API。 不要依赖记忆中的方法签名、参数、插件名称或属性名称。如果在提供的参考资料中找不到某个 API，请先获取相关文档页面，再作答。

值得指出的 Cordova 特有注意事项：

• 在操作任何 Scandit API 前，先等待 deviceready。 Cordova 插件系统会响应 deviceready 事件，填充 window.Scandit.* 并注册原生桥接；在模块加载时调用 Scandit.DataCaptureContext.initialize(...)（或其他 API）会遇到未定义的符号。始终使用 document.addEventListener('deviceready', () => { … }, false); 包装初始化代码。
• 使用方式是 Scandit.* 全局对象，而不是 import。 Cordova 的插件加载器会将所有 Scandit 类合并到 window.Scandit 上。在应用代码中使用 new Scandit.IdCapture(settings)、Scandit.IdCaptureRegion.Us、Scandit.RejectionReason.Timeout。应用代码中不要从 'scandit-cordova-datacapture-id' 导入 IdCapture（该路径仅在插件自身的 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 getter 是 mrzResult / vizResult（不是 Flutter 中的 mrz / viz）。其他特定来源的 getter：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 是包含两个可选方法的 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 插件不提供 JS 端的权限请求功能——如果想控制权限提示的时机，请安装 cordova-plugin-android-permissions（或调用项目已有权限插件的相机权限 API），并在挂载扫描视图前请求 CAMERA；否则，操作系统会在首次使用相机时提示。

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

这些 API 要么不存在，要么已被移除。请使用右侧的写法：

请勿写	请改用
import { IdCapture } from 'scandit-cordova-datacapture-id' in application code	new Scandit.IdCapture(settings) after deviceready (Cordova merges symbols onto window.Scandit)
Scandit.IdCapture.forContext(context, settings)	new Scandit.IdCapture(settings) then context.setMode(idCapture)
Scandit.IdCaptureOverlay.withIdCapture(...) / .withIdCaptureForView(...)	new Scandit.IdCaptureOverlay(idCapture) then view.addOverlay(overlay)
IdDocumentType enum / settings.supportedDocuments	settings.acceptedDocuments (document classes) + settings.scanner = new Scandit.IdCaptureScanner(new Scandit.FullDocumentScanner())
capturedId.documentType	capturedId.document?.documentType (IdCaptureDocumentType) or capturedId.isPassport() / isDriverLicense() / …
capturedId.isVisa() / capturedId.isVisaLetter()	capturedId.isVisaIcao() (Cordova ships only the ICAO visa)
capturedId.mrz / capturedId.viz (Flutter names)	capturedId.mrzResult / capturedId.vizResult
Scandit.IdCaptureRegion.us / Scandit.IdSide.front / Scandit.AamvaBarcodeVerificationStatus.authentic (lowercase Dart form)	Scandit.IdCaptureRegion.Us / Scandit.IdSide.Front / Scandit.AamvaBarcodeVerificationStatus.Authentic — Cordova 中 Scandit 的所有枚举成员都采用 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。
• 处理 didRejectId，而不只是 didCaptureId。 拒绝原因（Scandit.RejectionReason.Timeout、NotAcceptedDocumentType、DocumentExpired、DocumentVoided、ForgedAamvaBarcode 等）可以让用户知道扫描未成功的原因。生产环境中的集成必须向用户显示相关消息。
• 默认进行匿名化，除非你需要所有字段。 IdCaptureSettings.anonymizationMode 和针对各字段的 addAnonymizedField 可确保受监管的数据（例如文档图像、敏感字段）不会出现在结果中，除非你选择加入。
• 非 ID-Capture 问题请转交给 data-capture-sdk skill。 如果用户询问其他 Scandit 产品（Barcode Capture、SparkScan、MatrixScan、Label Capture 等），或询问如何在产品之间做选择，请转交给 data-capture-sdk skill，而不要猜测。

意图路由

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

• 从头开始集成 ID Capture（“为我的 Cordova 应用添加 ID 扫描”“扫描护照 / 驾驶执照”“读取 MRZ”“提取持有人的姓名和出生日期”）→ 阅读 references/integration.md 并遵循其中的说明。
• 三种附加功能之一（“拒绝已作废 / 已取消的 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 索引（参见下表中的 完整 API 参考），从中提取实际链接并访问。

URL 结构会因 SDK 版本和包路径而异，猜测 URL 会导致 404 错误。

框架变体策略

此技能中的示例使用纯 JavaScript / TypeScript（不绑定 UI 框架），因为官方的 IdCaptureSimpleSample 是纯 www/js/*.js，在 deviceready 后运行。如果项目在 Cordova 上使用 UI 框架（jQuery Mobile、Onsen UI、较旧的 Ionic v1 / Ionic v3 设置、Framework7），请保留相同的引导和 Scandit 调用，并将 view.connectToElement(...) 接入框架视图模板中的宿主 <div>。不要仅为了 ID Capture 引入新框架。

许可证密钥

扫描需要 Scandit 许可证密钥。对于此技能，许可证产品为 native，许可证平台为 ios 和 android。

按以下顺序操作——绝不要让用户等待 MCP：

1. Scandit MCP 服务已连接——调用 ensure_scanner_setup，传入产品 native、平台 ios 和 android、app_identifier（应用的 bundle 或 application id；对于 Web，传入其生产域名，绝不能是 localhost）以及环境变量 SCANDIT_LICENSE_KEY。不要运行它返回的命令。然后使用密钥 ID 调用 get_license_key，该 ID 可从此结果或 list_license_keys 获取；如果 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 返回的密钥，也可以是用户粘贴或提供的密钥——聊天中仍只显示经过掩码处理的预览。不要在项目、其文件或环境中搜索密钥。

参考资料

根据用户的问题，为其指引合适的资源：

主题	资源
Cordova 集成	开始使用 · 示例（IdCaptureSimpleSample）
高级主题（匿名化、验证、扫描器、覆盖层）	高级配置
不同主要 SDK 版本之间的迁移	7 → 8
完整 API 参考	ID Capture API