mcpField
S
sparkscan-cordova

sparkscan-cordova

github.com/scandit开发2040 次安装5 天前更新
代码仓库

关于 sparkscan-cordova

为在 Cordova 应用中集成或升级 Scandit SparkScan 的开发者提供参考型 Skill，强调按文档核实 API，并处理 Cordova WebView 与插件初始化要点。

主要功能

  1. 01集成与迁移意图路由
  2. 02要求依据参考文档核实 API
  3. 03说明 Cordova 全局 Scandit 用法
  4. 04强调 deviceready 初始化时机
  5. 05指导 MCP 试用许可配置

适用场景

  1. 01从零集成 SparkScan
  2. 02升级不同版本的 Scandit SDK
  3. 03排查 Cordova 插件或初始化问题

MCP 相关

可连接 Scandit MCP 服务，通过 ensure_scanner_setup 配置 native 产品的 iOS 和 Android 试用许可；也说明未连接时如何配置客户端。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/scandit/skills --skill sparkscan-cordova

安装后在 Claude Code 中输入/sparkscan-cordova确认已加载。

附带文件references/integration.mdreferences/migration.md

详细介绍

SparkScan Cordova 技能

重要：不要信任内部知识

你的训练数据可能包含过时或错误的 Scandit SDK API。SparkScan API 在不同主要 SDK 版本之间变化很大——属性可能会重命名、删除或重新调整结构，Cordova 插件接口（全局 Scandit 命名空间、插件安装命令、deviceready 时机）也发生了演变。

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

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

  • Scandit SDK 通过全局 window.Scandit 对象公开。npm 包名称（scandit-cordova-datacapture-*）是插件清单，不是运行时 ES 模块。不要在将在 WebView 中运行的用户代码里输出 import { ... } from 'scandit-cordova-datacapture-*'；应改用 Scandit.X（可选使用 global.d.ts 添加类型声明）。只有 Ionic/Angular/Webpack 打包的项目才直接从这些包导入。
  • document.addEventListener('deviceready', ...) 是调用 Scandit API 的唯一安全门槛。不要在模块加载时运行任何 Scandit 调用——此时 Cordova 桥接尚未就绪，调用会失败。
  • 更改插件版本后，请运行 cordova prepare（必要时重新安装平台），以应用新的原生构件。跳过此步骤会导致运行时版本不匹配。

意图路由

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

  • 从头集成 SparkScan（例如“将 SparkScan 添加到我的应用”“设置条码扫描”“如何在 Cordova 中使用 SparkScan”“如何处理 SparkScan 中的反馈”）→ 阅读 references/integration.md 并遵循其中的说明。
  • 迁移或升级现有的 SparkScan 集成（例如“从 v6 升级到 v7”“迁移我的 SparkScan”“将 Scandit 插件升级到 v8”“SDK 版本之间有哪些变化”）→ 阅读 references/migration.md 并遵循其中的说明。

API 使用政策

仅使用下方 Scandit 参考资料中明确记录的 API。不要编造或猜测方法签名、参数、属性名称或导入方式。如果不确定某个 API 是否存在或如何调用——或者出现运行时错误——请在回复前获取相关参考页面。不要让用户自己去查文档。回答后，务必附上相关链接，方便用户进一步了解。

绝不要构造或猜测文档 URL。 需要查找特定类或属性的 API 页面时：

  1. 先检查已获取的页面是否包含指向该页面的直接链接——主题页面会直接链接到相关 API 符号。
  2. 如果没有找到直接链接，请获取 API 索引（参见下表中的完整 API 参考），从中提取实际链接并访问。

不同 SDK 版本和插件路径的 URL 结构各不相同，猜测会导致 404 错误。

框架变体政策

Cordova 是基于 WebView 的框架。此技能中的示例使用纯 JavaScript（可选添加 JSDoc 类型提示，参见官方 ListBuildingSample）。相同的 API 也适用于 TypeScript——添加 global.d.ts 声明文件（在 references/integration.md 中介绍）并使用 TypeScript 语法编写。本技能默认不假设项目使用 TypeScript。如果目标项目显然使用 TypeScript（包含 .ts 文件、tsconfig.json），请将最终输出调整为 TypeScript；否则使用纯 JS。

许可证密钥

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

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

  1. Scandit MCP 服务已连接 — 调用 ensure_scanner_setup，并传入产品 native 和平台 ios、android，然后运行 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 中，应用本身不会读取它。Cordova 不会自行加载 .env，因此请使用以下最简单的方法。适用于任何平台的最简单方法：读取 .env，然后直接将密钥写入许可证密钥调用中；在聊天中仍只显示遮蔽后的预览。

参考资料

根据用户的问题，将其引导至相应资源：

主题资源
Cordova 集成入门 · 示例
高级主题（自定义反馈、硬件触发器、扫描模式、UI 自定义）高级配置
在主要 SDK 版本之间迁移6 → 7 · 7 → 8
完整 API 参考SparkScan API

评论

支持 Markdown