--- title: SDK 实施最佳实践 canonical: https://developer.unico.io/zh-CN/dual-api/developers/sdks-and-tools/best-practices-for-sdk-implementation locale: zh-CN generated_by: markdown-export --- - [/zh-CN/](/zh-CN/) - [SDK 与工具](/zh-CN/dual-api/developers/sdks-and-tools/overview) - SDK 实施最佳实践 **本页内容# SDK 实施最佳实践 本页汇总了集成和维护 Unico SDK 的最重要准则。遵循这些实践可减少集成错误、防止安全事件，并确保生产环境顺利上线。 ### 入门指南​ 使用 PoC 辅助实施 Unico 提供涵盖所有支持语言的功能性代码示例概念验证（PoC），展示预期的方法调用顺序和集成模式。请通过客户门户支持工单系统访问可用的 PoC。 始终保持 SDK 为最新版本 SDK 持续演进以提供更高的安全性和新功能。及时应用更新——尤其是关键更新——至关重要。请参阅[更新政策](/zh-CN/dual-api/developers/sdks-and-tools/update-policy)了解时间表和相关义务。 确认最新可用版本 通过各平台的发行说明查看当前版本： [Android 发行说明](/zh-CN/developers/sdks-and-tools/android/resources/release-notes) [iOS 发行说明](/zh-CN/developers/sdks-and-tools/ios/resources/release-notes) [Flutter 发行说明](/zh-CN/developers/sdks-and-tools/flutter/resources/release-notes) [Web 发行说明](/zh-CN/dual-api/developers/sdks-and-tools/web/web-sdk/resources/release-notes) ### 更新策略​ 避免同时更新 SDK 和其他组件 您的应用程序可能会与 Unico SDK 一起加载多个库。同时升级多个依赖项会增加定位故障根本原因的难度。请单独更新 SDK，并在[预发布环境](#perform-tests-in-unicos-staging-environment)中验证后，再与其他变更合并。 获取 SDK 更新支持 提交更新问题支持工单时，请包含以下信息： SDK 语言和实施类型（原生或混合） 使用的框架 当前版本和目标版本 API Key 变更说明及复现步骤 结果、错误、日志、截图或视频 ### JWT 安全​ 不要操作 JWT 对象 请勿打开或修改加密的 JWT成功采集后返回的 JWT 是**加密的**。请勿打开、解析或序列化它。其内部结构可能随时发生变化，恕不另行通知。仅在向 Unico API 提交图像时使用它。 如需图像预览，请使用 JWT 附带的 Base64 属性——切勿自行解码 JWT。 在 10 分钟内发送 JWT 警告出于安全原因，JWT 必须在采集后 **10 分钟内**发送至 Unico 后端。超时提交的数据包将被作废。 JWT 仅可提交一次 警告JWT 只能提交**一次**。如果提交过程中发生错误，必须重新进行生物特征采集——不得重复使用同一个 JWT。 ### 测试准则​ 不要使用虚拟化或模拟器 在虚拟机或模拟器中运行 SDK 会触发安全错误代码（`73006`、`73600`、`73400`）。请始终在**物理设备**上进行测试，以避免误判错误和不必要的返工。 Web 采集期间不要保持 DevTools 开启 Web SDK 将开启的 DevTools 检测为潜在的欺诈信号，并使提交失效。在运行端到端采集测试前，请关闭 DevTools。 ### 在 Unico 预发布环境中执行测试​ 在上线生产之前，请在 Unico 的预发布环境中以真实场景进行充分测试。使用预发布专用的 API Key 和配置——切勿在测试中使用生产凭据。 ### 平台特定准则​ Flutter：使用 Unico 的 Flutter 插件 不要尝试在 Flutter 应用中桥接原生 Android 或 iOS SDK。原生桥接经常产生未映射的错误。请始终使用 Unico 专用的 Flutter 插件。 Web：更新版本时删除旧资源文件 升级 Web SDK 时，请在插入新文件之前从 `public` 文件夹中删除旧资源文件。同名文件不会自动覆盖，可能导致版本冲突。 移动端：构建新版本前清除缓存 旧版 SDK 的构建产物可能在更新后引发依赖错误。在构建新版本之前： **Flutter：** 删除 `pubspec.lock` 并运行 `flutter pub get` **iOS：** 运行 `pod cache clean --all` 和 `pod install` **Android：** 运行 `./gradlew clean` 混淆设置 将 Unico SDK 代码排除在混淆配置之外。混淆 SDK 通常会导致发布版本出现调试版本中未出现的故障。请参阅平台特定文档了解所需的保留规则。 ### 用户体验与性能​ 将准备和摄像头开启流程分为两个步骤 将 SDK 流程分为两个独立阶段： **准备** — 在页面加载时（用户交互之前）初始化 SDK。 **开启** — 仅在用户明确触发操作时启动摄像头。 提前准备 SDK 可减少感知延迟，显著提升用户体验。 ### 生产发布​ 为生产发布创建安全检查清单 部署至生产环境之前，请验证： 生产 API Key 和环境配置正确无误 回滚计划已定义并经过测试 日志收集协议已就位 已记录处理故障的支持工单流程 所有验证均已在预发布环境中通过 最后更新 于 2026年10月8日**