--- title: 最佳实践 description: 集成、更新、测试并安全上线 Unico SDK 的准则，包括预发布（UAT）环境的安全规则。 canonical: https://developer.unico.io/zh-CN/developers/sdks-and-tools/best-practices-for-sdk-implementation locale: zh-CN generated_by: markdown-export --- - [/zh-CN/](/zh-CN/) - [SDK 与工具](/zh-CN/developers/sdks-and-tools/overview) - 最佳实践 **本页内容# 最佳实践 本页汇总了集成和维护 Unico SDK 的最重要准则。遵循这些实践可减少集成错误、防止安全事件，并确保生产环境顺利上线。 ### 入门指南​ 从参考应用开始 Unico 在 [reference-apps](https://github.com/unico-labs/reference-apps) 仓库中为每个 SDK 提供了参考应用。每个应用都实现了完整的用户旅程。 始终保持 SDK 为最新版本 SDK 持续演进以提供更高的安全性和新功能。及时应用更新——尤其是关键更新——至关重要。请参阅[更新政策](/zh-CN/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 — Journeys SDK 发行说明](/zh-CN/developers/sdks-and-tools/web/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 和配置——切勿在测试中使用生产凭据。 IDCloud 的预发布环境（UAT）采用**与生产环境相同的安全标准**。以下准则说明了原因，以及如何在不受中断的情况下进行测试。 预发布环境的变化 **此前 — 检测但不拒绝** 偏离真实使用模式的条件会被识别，但不会阻止采集。 **现在 — 检测并拒绝** 相同的条件现在会导致活体检测被拒绝，严格程度与生产环境一致。 为什么存在此限制 **保真性 — 与生产环境保持一致** 在预发布环境中通过的内容，在生产环境中必须表现一致——避免在测试中已通过的集成在上线后意外失败。 可以做什么，不可以做什么 在接近真实使用的条件下进行测试时，安全层不会影响您的开发。 非市场标准的开发工具会触发安全校验，交易可能被拦截。 场景状态完整的集成流程——采集、提交、API 响应与返回✅ 可以功能场景：UI/UX、性能、业务错误✅ 可以处于终端用户标准配置的设备✅ 可以与后端、API 和数据处理的集成✅ 可以已 root/越狱的设备❌ 不可以启用调试模式 / USB 调试❌ 不可以模拟器或虚拟化❌ 不可以虚拟摄像头或采集自动化工具❌ 不可以更改连接的工具❌ 不可以设备上的企业 MDM 或活动监控❌ 不可以容器或虚拟机中的沙箱❌ 不可以 上述任何条件都可能导致活体检测被拒绝。 您的 QA 流程依赖上述某个条件吗？请联系[支持团队](https://business.unico.io/hc/)获取环境配置方面的指导。不存在例外、临时放行或暂时放宽——Unico 会在其认为必要的期间内保持预发布环境与生产环境一致。 ### 平台特定准则​ 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月23日**