SmileID SmartSelfie Enrollment / Authentication SDK 接入说明

官方文档：

SmartSelfie Enrollment and Authentication：https://docs.usesmileid.com/integration-options/mobile/products/smartselfie-tm-enrollment-and-authentication
Mobile Getting Started：https://docs.usesmileid.com/integration-options/mobile/getting-started

LLM 速览

SmartSelfie Enrollment / Authentication 是 SmileID 移动端 SDK 的人脸注册和人脸认证能力。它负责在 App 内展示指引、申请相机权限、采集自拍图和活体图，并可选择自动提交 SmileID API。

关键结论：

Enrollment：用于用户首次注册人脸。
Authentication：用于已注册用户后续刷脸认证。
如果业务目标是“当前自拍 vs 证件照 / NIDA 照片”的一次性比对，应优先使用 SmartSelfie Compare。
如果只想使用 SmileID 的采集组件，设置 skipApiSubmission = true，由 App 上传图片到后台，再由后台调用 Compare 或其他身份核验服务。
如果设置 skipApiSubmission = false，SDK 会自动提交 SmileID API，后台仍应通过 callback 或 job status 判断最终结果。

1. 能力边界

能力	使用场景	推荐入口
SmartSelfie Enrollment	用户首次注册人脸	`SmileID.SmartSelfieEnrollment`
SmartSelfie Authentication	已注册用户再次刷脸认证	`SmileID.SmartSelfieAuthentication`
SmartSelfie Compare	当前自拍与参考图一次性比对	REST API `/v2/smart-selfie-compare`

官方 SmartSelfie Authentication flow 的高层步骤：

展示用户操作说明。
请求相机权限。
采集并保存活体图和自拍图。
提交 job 到 Smile ID API。
将结果返回给调用方。

2. 支持的 SDK 集成形态

平台	Enrollment 入口	Authentication 入口
Android Jetpack Compose	`SmileID.SmartSelfieEnrollment`	`SmileID.SmartSelfieAuthentication`
Android Fragment	`SmartSelfieEnrollmentFragment`	`SmartSelfieAuthenticationFragment`
iOS SwiftUI	`SmileID.smartSelfieEnrollmentScreen(...)`	`SmileID.smartSelfieAuthenticationScreen(...)`
iOS UIKit	通过 SwiftUI view 嵌入 UIKit	通过 SwiftUI view 嵌入 UIKit
Flutter	`SmileIDSmartSelfieEnrollment`	`SmileIDSmartSelfieAuthentication`
React Native	`SmileIDSmartSelfieEnrollmentView`	`SmileIDSmartSelfieAuthenticationView`
React Native Expo	`SmileIDSmartSelfieEnrollmentView`	`SmileIDSmartSelfieAuthenticationView`

3. SDK 基础接入

接入前准备：

项目	官方要求
Android	Android 5.0+，API level 21+
Android 设备	需要 Google Play Services
iOS	iOS 13+，Xcode 14+
Flutter	Flutter 3.0.0+，Dart 3.0.5+
React Native	React Native 0.70+
React Native Expo	React Native 0.79.1+，Expo 53.0.0+
Smile 配置	从 Smile ID Portal 的 Security Settings 下载 `smile_config.json`

注意：

smile_config.json 和环境、API Key 绑定，Sandbox / Production 需要分别配置。
Android 原生官方建议使用 11.0.2 或更高版本。

Android 依赖示例：

kotlin

implementation("com.smileidentity:android-sdk:<latest-version>")

Android 配置文件位置：

text

src/main/assets/smile_config.json

iOS 可通过 Swift Package Manager 或 CocoaPods 接入：

ruby

pod 'SmileID'

iOS 需要确保 smile_config.json 加入 app target，并在 Build Phases 的 Copy Bundle Resources 中可见。

4. SDK 初始化

官方建议初始化时机：

平台	初始化位置
Android	`Application.onCreate`
iOS	`AppDelegate.application(_:didFinishLaunchingWithOptions:)` 或 `SceneDelegate`
Flutter	`main.dart` 中调用 `initializeWithConfig`
React Native	`App.tsx` 等 app 入口调用 `initialize`

Callback URL：

可通过 setCallbackUrl 为 job 设置 callback URL。
SDK 自动提交 SmileID API 时，建议配置 callback URL，便于后台接收最终结果并归档。

环境切换：

官方 Getting Started 中环境由初始化函数第一个参数 useSandBox 决定。
接入时需要结合当前 SDK 版本类型定义和实测结果确认 Sandbox / Production 没有配置反。

5. 入参参数

参数	是否必填	说明
`userId`	Enrollment 可选；Authentication 必填	绑定 SmartSelfie Registration 的用户 ID；Enrollment 不传时官方会随机生成；Authentication 必填
`jobId`	否	本次 SmartSelfie job ID；建议业务侧生成并保证唯一
`allowAgentMode`	否	是否允许 Agent Mode；允许时界面会显示前后摄像头切换
`allowNewEnroll`	否	是否允许同一个 `userId` 再次 Enrollment
`showAttribution`	否	是否在 Instructions 页面展示 Smile ID attribution
`showInstructions`	否	官方描述为是否停用 SmartSelfie 采集页面指引；建议以实际 SDK 行为确认
`skipApiSubmission`	否	是否只采集图片、不提交 SmileID API
`extraPartnerParams`	否	合作方自定义透传参数
`colorScheme`	否	主题配置
`typography`	否	字体配置
`onResult`	Android 必填	SmartSelfie Registration 完成回调
`delegate`	iOS 必填	SmartSelfie flow 结果回调对象

6. 关键参数说明

6.1 userId

userId 应优先使用业务系统生成的稳定用户标识。

Enrollment 阶段：建议传入业务用户 ID，不依赖 SDK 随机生成。
Authentication 阶段：必须传入已注册过的同一个 userId。

6.2 jobId

jobId 建议由业务后台或 App 统一生成，并保证每次任务唯一，用于关联：

SDK 回调。
开户申请号。
后台 job status 查询。
审计、对账和问题排查。

6.3 skipApiSubmission

值	行为
`false`	SDK 采集图片后自动提交 SmileID API，并返回 API / job status 相关结果
`true`	SDK 只采集图片，不提交 SmileID API，只返回自拍图和活体图文件路径

注意：

skipApiSubmission 不是“是否使用 SDK”的开关。
它控制的是采集完成后是否由 SDK 自动提交 SmileID API。
如果设为 true，后续需要 App 将图片上传到后台，由后台决定调用 SmartSelfie Compare、其他 SmileID API 或其他供应商。

7. 出参结果

Android / 原生 SDK 成功结果通常包含：

字段	说明
`selfieFile`	SDK 采集到的自拍图文件
`livenessFiles`	SDK 采集到的活体图文件列表
`jobStatusResponse`	SmileID API 最新 job status 响应

官方特别提示：即使 API submission 成功，jobStatusResponse 也可能表示 job 仍在处理中或失败，因此不能只看 SDK 成功回调，还要继续判断：

jobStatusResponse.jobSuccess
jobStatusResponse.jobComplete

React Native onResult 示例结构：

json

{
  "selfieFile": "<path to selfie file>",
  "livenessFiles": "<path to liveness files>",
  "apiResponse": {
    "code": "...",
    "created_at": true,
    "job_id": true,
    "job_type": "",
    "message": "",
    "partner_id": "",
    "partner_params": "",
    "status": "",
    "updated_at": "",
    "user_id": ""
  }
}

skipApiSubmission = true 时只返回采集文件：

json

{
  "selfieFile": "<path to selfie file>",
  "livenessFiles": "<path to liveness files>"
}

常见错误类型：

相机权限拒绝。
采集失败。
网络异常。
API 提交失败。
SDK 初始化或配置异常。

8. 推荐接入流程

8.1 SDK 自动提交 SmileID API

适用于希望由移动端 SDK 完整处理采集和提交的场景。

text

App 初始化 SmileID SDK
  -> 设置 callback URL
  -> 首次注册：调用 SmartSelfieEnrollment
  -> 后续认证：调用 SmartSelfieAuthentication
  -> SDK 请求相机权限
  -> SDK 采集 selfieFile / livenessFiles
  -> SDK 自动提交 SmileID API
  -> App 接收 onResult / delegate 回调
  -> App / 后台根据 jobStatusResponse 或 callback 结果判断最终状态

建议：

skipApiSubmission = false。
userId 使用业务系统内稳定用户 ID。
jobId 每次生成唯一值。
后台保存 userId、jobId、SmileID 返回结果和原始回调。

8.2 SDK 只采集图片，后台自行提交

适用于希望后台统一调用 SmileID REST API、统一做审计和供应商路由的场景。

text

App 初始化 SmileID SDK
  -> 调用 SmartSelfieEnrollment / Authentication
  -> 设置 skipApiSubmission = true
  -> SDK 请求相机权限
  -> SDK 采集 selfieFile / livenessFiles
  -> SDK 返回本地文件路径
  -> App 上传自拍图和活体图到后台
  -> 后台调用 SmartSelfie Compare 或其他供应商接口
  -> 后台返回 KYC / 认证结果给 App

对传音银行当前开户链接，如果证件照来自 Softnet / NIDA，最终比对由第三层身份核验整合系统完成，App 侧更适合把 SmileID SDK 当成“自拍图和活体图采集组件”使用，即 skipApiSubmission = true。

9. 接入注意事项

Authentication 必须使用已完成 Enrollment 的 userId。
userId 和 jobId 建议由业务系统生成，不建议完全依赖 SDK 随机生成。
skipApiSubmission = true 时，SDK 不会提交 SmileID API，也不会返回 API 结果。
skipApiSubmission = false 时，SDK 会自动提交 SmileID API，应配置 callback URL 方便后台接收最终结果。
Android Fragment 示例官方提示：即使 API submission 成功，也要检查 jobStatusResponse。
React Native / Flutter 官方有 known issue 提示：建议将 SmartSelfie 组件放在可导航进入和退出的页面容器内，避免失败弹窗持续显示。
smile_config.json 按环境区分，Sandbox / Production 不能混用。
如果业务目标是一次性人脸比对，优先选 SmartSelfie Compare。
如果业务目标是长期复用同一个用户的人脸模板，再使用 Enrollment + Authentication。

SmileID SmartSelfie Enrollment / Authentication SDK 接入说明 ​

LLM 速览 ​

1. 能力边界 ​

2. 支持的 SDK 集成形态 ​

3. SDK 基础接入 ​

4. SDK 初始化 ​

5. 入参参数 ​

6. 关键参数说明 ​

6.1 userId ​

6.2 jobId ​

6.3 skipApiSubmission ​

7. 出参结果 ​

8. 推荐接入流程 ​

8.1 SDK 自动提交 SmileID API ​

8.2 SDK 只采集图片，后台自行提交 ​

9. 接入注意事项 ​

SmileID SmartSelfie Enrollment / Authentication SDK 接入说明

LLM 速览

1. 能力边界

2. 支持的 SDK 集成形态

3. SDK 基础接入

4. SDK 初始化

5. 入参参数

6. 关键参数说明

6.1 userId

6.2 jobId

6.3 skipApiSubmission

7. 出参结果

8. 推荐接入流程

8.1 SDK 自动提交 SmileID API

8.2 SDK 只采集图片，后台自行提交

9. 接入注意事项