用户旅程

用户旅程（User Journeys）是由 SDK 与已配置流程协同编排的多步骤采集会话。例如，idchecktrustdocssign 流程将在单个会话中依次执行自拍、证件拍摄和签名。

使用场景

可用的旅程取决于为您的集成所配置的流程。请参阅使用场景，了解使用场景 → 流程 → 能力的完整映射关系。

工作原理

该插件委托底层原生 SDK 执行：

插件通过 SmartFrame 叠加层打开摄像头（Android 或 iOS）。
原生 SDK 编排流程所需的采集序列（自拍、证件、签名）。
SDK 在内部将结果转发给 Unico——客户端不会直接接收或管理图像数据。
通过平台通道返回包含 processId 的 SuccessResult 对象。

编排完全由 SDK 处理——您无需在 Dart 代码中实现步骤序列。

摄像头模式（智能采集）

SDK 默认启用智能取景和自动采集。在构建器中按如下方式配置摄像头模式：

UnicoCheckCameraOpener _opener = new UnicoCheck(this)
    .setAutoCapture(autoCapture: true)
    .setSmartFrame(smartFrame: true)
    .build();

提示

上述方法的 false/true 值不会改变采集体验；它们仅用于 SDK 的内部逻辑。

启动用户旅程

步骤 1 — 实现 UnicoListener

UnicoListener 处理 SDK 生命周期回调。实现以下四个必须方法：

方法	调用时机
`onErrorUnico(error)`	SDK 运行过程中发生错误
`onUserClosedCameraManually()`	用户手动关闭相机
`onSystemClosedCameraTimeoutSession()`	达到 40 秒会话限制
`onSystemChangedTypeCameraTimeoutFaceInference()`	13 秒内未检测到人脸 — 切换为手动拍摄

class _MyHomePageState extends State<MyHomePage> implements UnicoListener {
  late UnicoCheckBuilder _unicoCheck;

  @override
  void onErrorUnico(UnicoError error) {}

  @override
  void onUserClosedCameraManually() {}

  @override
  void onSystemClosedCameraTimeoutSession() {}

  @override
  void onSystemChangedTypeCameraTimeoutFaceInference() {}
}

必须实现的监听器方法

上述四个监听器方法必须在您的项目中创建（即使没有任何逻辑）。否则，项目将无法成功编译。

步骤 2 — 在 UnicoSelfie 上实现旅程监听器

将旅程回调添加到您的状态类中：

方法	描述
`onSuccess(SuccessResult result)`	采集成功——返回包含 `processId` 的 `SuccessResult`（Unico 在内部处理图像）
`onErrorSelfie(UnicoError error)`	采集失败——返回包含代码和描述的 `UnicoError`

无图像数据

与 Liveness 流程不同，用户旅程回调不返回 base64 或 encrypted。Unico 在内部处理图像，仅返回 processId。

@override
void onSuccess(SuccessResult result) {
  debugPrint('processId: ${result.processId}');
}

@override
void onErrorSelfie(UnicoError error) { }

步骤 3 — 调用 openCameraSelfie

openCameraSelfie 方法用于打开摄像头。对于用户旅程，请传入 Unico 提供的 webAppToken，而非 JSON 凭证文件：

_opener.openCameraSelfie(
  listener: this,
  webAppToken: token,
);

监控数据收集

openCameraSelfie 方法提供了一个重载，可通过 UnicoCheckPrepareInfo 接受元数据，以协助识别用户会话和流程：

externalUserId（String，必填）——您系统中的用户标识符。传输前自动使用 SHA-256 进行哈希处理。
useCase（String，可选）——当前运行的上下文或流程标识符。以明文方式传输。

_opener.openCameraSelfie(
  listener: this,
  webAppToken: token,
  prepareInfo: UnicoCheckPrepareInfo(
    externalUserId: 'external_user_id',
    useCase: 'use_case', // optional
  ),
);

有关完整的结果处理，请参阅接收结果。