跳转到主要内容

最佳实践

Markdown

本页汇总了集成和维护 Unico SDK 的最重要准则。遵循这些实践可减少集成错误、防止安全事件，并确保生产环境顺利上线。

入门指南​

从参考应用开始

Unico 在 reference-apps 仓库中为每个 SDK 提供了参考应用。每个应用都实现了完整的用户旅程。

始终保持 SDK 为最新版本

SDK 持续演进以提供更高的安全性和新功能。及时应用更新——尤其是关键更新——至关重要。请参阅更新政策了解时间表和相关义务。

确认最新可用版本

通过各平台的发行说明查看当前版本：

更新策略​

避免同时更新 SDK 和其他组件

您的应用程序可能会与 Unico SDK 一起加载多个库。同时升级多个依赖项会增加定位故障根本原因的难度。请单独更新 SDK，并在预发布环境中验证后，再与其他变更合并。

获取 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 流程依赖上述某个条件吗？

请联系支持团队获取环境配置方面的指导。不存在例外、临时放行或暂时放宽——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 流程分为两个独立阶段：

  1. 准备 — 在页面加载时（用户交互之前）初始化 SDK。
  2. 开启 — 仅在用户明确触发操作时启动摄像头。

提前准备 SDK 可减少感知延迟，显著提升用户体验。

生产发布​

为生产发布创建安全检查清单

部署至生产环境之前，请验证：

  • 生产 API Key 和环境配置正确无误
  • 回滚计划已定义并经过测试
  • 日志收集协议已就位
  • 已记录处理故障的支持工单流程
  • 所有验证均已在预发布环境中通过
最后更新 于