---
title: Web 采集
description: 在 Web 应用中运行 Journey 流程的采集,可使用托管链接或 Journeys SDK,并使用 Human Plugin 创建请求返回的内容。
canonical: https://developer.unico.io/zh-CN/human-plugin/integrations/web
locale: zh-CN
generated_by: markdown-export
---

# Web 采集

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

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

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

`token` 和 `link` **仅**在创建时返回。请在同一个请求中将它们传递给前端,或自行存储。请参阅 [Human Token Journey](/zh-CN/human-plugin/integrations/human-token-journey)。

<a id="requirements"></a>

## 要求

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

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

- 页面必须通过 **HTTPS** 提供。摄像头只能在[安全上下文](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts)中工作。
- 应用内浏览需要 Android 8(API 26)或 iOS 13 及更高版本。
- 不支持社交网络应用内置的浏览器。

<a id="choose-a-model"></a>

## 选择模式

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

### 托管链接

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

```json
{
  "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()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) 打开 `link`,监视该标签页是否到达 `callbackUri`,并将其关闭。

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

```mermaid
sequenceDiagram
  participant F as Your front-end
  participant B as Your back-end
  participant H as Human Plugin
  participant P as Hosted page
  F->>B: start the capture
  B->>H: POST /v1/processes (Journey flow, callbackUri)
  H-->>B: 201, id + token + link
  B-->>F: id + link
  F->>P: open link
  Note over P: capture
  P-->>F: back to callbackUri
  F->>B: capture ended
  B->>H: GET /v1/processes/{id}
  H-->>B: 200, final state
```

### Journeys SDK

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

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

<a id="1-install"></a>

#### 1. 安装

```bash
npm install unico-journey-sdk
```

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

<a id="2-allow-the-sdk-in-your-headers"></a>

#### 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")
```

<a id="3-initialize"></a>

#### 3. 初始化

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

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

ByUnicoSDK.init({ token });
```

<a id="4-open-the-capture"></a>

#### 4. 打开采集

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

```javascript
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` 将用户带到下一个界面,并避免在用户重新开始时立即创建新的流程。

```mermaid
sequenceDiagram
  participant F as Your front-end
  participant S as Journeys SDK
  participant B as Your back-end
  participant H as Human Plugin
  F->>B: start the capture
  B->>H: POST /v1/processes (Journey flow)
  H-->>B: 201, id + token + link
  B-->>F: id + token
  F->>S: init({ token })
  F->>S: open({ transactionId: id, token, onFinish })
  Note over S: capture
  S-->>F: onFinish
  F->>B: capture ended
  B->>H: GET /v1/processes/{id}
  H-->>B: 200, final state
```

<a id="troubleshooting"></a>

#### 故障排查

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

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

> **警告: 不受支持的设置**
>
> - **在移动端 WebView 中使用 SDK。** 在应用中,请改为打开 `link`。请参阅 [Android](/zh-CN/human-plugin/integrations/android)、[iOS](/zh-CN/human-plugin/integrations/ios)、[Ionic](/zh-CN/human-plugin/integrations/ionic)、[React Native](/zh-CN/human-plugin/integrations/react-native) 和 [Flutter](/zh-CN/human-plugin/integrations/flutter) 指南。
> - **使用您自己的 `<iframe>` 指向采集页面。** 请使用 SDK,由它来管理 iFrame。