Web 采集

使用 Human Plugin 返回的令牌和链接,引导用户在浏览器中完成采集。

Markdown

您的后端使用 Journey 流程在 Human Plugin 中创建流程。201 响应包含前端所需的三个值:

字段	用途
id	Human Plugin 流程 id。SDK 将其作为 transactionId,您的后端也用它读取结果
token	在 Journeys SDK 中启动采集
link	托管的采集页面

token 和 link 仅在创建时返回。请在同一个请求中将它们传递给前端,或自行存储。请参阅 Human Token Journey。

要求

采集在浏览器中运行,需要访问摄像头。

操作系统	Chrome	Firefox	Safari	Samsung Internet	Opera	Edge
Windows	✅	✅	N/A	N/A	❌	❌
macOS	✅	✅	✅	N/A	❌	❌
Android	✅	❌	N/A	✅	❌	❌
iOS	✅	✅	✅	N/A	❌	❌

• 页面必须通过 HTTPS 提供。摄像头只能在安全上下文中工作。
• 应用内浏览需要 Android 8(API 26)或 iOS 13 及更高版本。
• 不支持社交网络应用内置的浏览器。

选择模式

模式	最适合
托管链接	最简单的设置。无需库:用户前往 link,完成后返回您的 callbackUri
Journeys SDK	采集在您的页面内打开,用户无需离开页面

托管链接

在创建请求中发送 callbackUri。它是采集结束时用户返回的页面。

{
  "flow": "humantoken",
  "clientId": "client-a",
  "correlationId": "order-1001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
  "callbackUri": "https://app.example.com/capture/done"
}

然后通过以下两种方式之一将用户送到 link:

• 重定向。 导航到 link。采集结束时,用户会被送回 callbackUri。
• 新标签页。 使用 window.open() 打开 link,监视该标签页是否到达 callbackUri,并将其关闭。

用户返回后,通知您的后端,由后端调用 GET /v1/processes/{id}。

Journeys SDK

SDK 会在您的页面上以 iFrame 打开采集。它适用于任何框架(React、Angular、Vue)或原生 JavaScript。

开始之前,请联系 Unico 支持团队注册您的域名。这些域名必须使用 HTTPS。

1. 安装

npm install unico-journey-sdk

SDK 遵循语义化版本控制,因此可以放心升级次版本和补丁版本。请保持更新:安全修复和缺陷修复会随新版本发布。

2. 在您的标头中允许 SDK

如果您的页面不发送 Content-Security-Policy 或 Permissions-Policy 标头,请跳过此步骤。否则,请添加:

Content-Security-Policy:

frame-src https://*.unico.io https://*.unico.app;
script-src https://idpay.unico.io;
style-src https://idpay.unico.io;
connect-src https://api.cadastro.unico.app;

Permissions-Policy:

camera=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io"),
geolocation=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io")

3. 初始化

一旦知道需要采集,就调用 init。它会预加载采集。

import { ByUnicoSDK } from 'unico-journey-sdk';

ByUnicoSDK.init({ token });

4. 打开采集

参数	是否必填	值
transactionId	是	Human Plugin 的 id
token	是	创建请求返回的 token
onFinish	是	采集结束或用户关闭采集时调用
onWidgetVisibilityChange	否	采集显示或隐藏时调用

ByUnicoSDK.open({
  transactionId: id, // the Human Plugin id
  token,
  onFinish: ({ type }) => {
    if (type === 'FINISH') {
      // The capture ended. Ask your back-end to read the outcome.
    }
    // type === 'CLOSE': the person closed it before the end.
  },
  // Optional: hide your own overlays while the capture is visible.
  onWidgetVisibilityChange: (visible) => {},
});

// To close it yourself:
ByUnicoSDK.close();

onFinish 会收到:

字段	说明
type	采集结束时为 'FINISH',用户提前关闭时为 'CLOSE'
transaction.redirectUrl	接下来将用户送往的位置。仅在 'FINISH' 时存在

警告

onFinish 只表示采集已结束,不表示结果如何。结果只能通过您后端的 GET /v1/processes/{id} 获得。

也请使用 onFinish 将用户带到下一个界面,并避免在用户重新开始时立即创建新的流程。

故障排查

• 流程中断或行为异常。 请确保您的任何脚本都没有修改 DOM 中 SDK 的 iFrame。
• 采集界面外观不同。 宽泛的 CSS 规则(例如标签选择器)可能会影响到 iFrame。SDK 自身的 id 和 class 均以 unico 开头。
• 更新后出现意外错误。 请仅通过 npm 或 yarn 安装 SDK,切勿编辑其文件。

测试

进行端到端采集测试前,请关闭浏览器开发者工具。打开的开发者工具会阻止提交。

不受支持的设置

• 在移动端 WebView 中使用 SDK。 在应用中,请改为打开 link。请参阅 Android、iOS、Ionic、React Native 和 Flutter 指南。
• 使用您自己的 <iframe> 指向采集页面。 请使用 SDK,由它来管理 iFrame。