跳转到主要内容

SDK 实施最佳实践

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

入门指南​

使用 PoC 辅助实施

Unico 提供涵盖所有支持语言的功能性代码示例概念验证（PoC），展示预期的方法调用顺序和集成模式。请通过客户门户支持工单系统访问可用的 PoC。

始终保持 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 和配置——切勿在测试中使用生产凭据。

平台特定准则​

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