# @getyoti/react-face-capture 中文文档

规范地址：https://npmcn.com/package/%40getyoti/react-face-capture/

版本：2\.11\.0
npm 元数据更新时间：2026-10-28T16:26:22.807Z
中文译文更新时间：2026-11-16T07:04:53.576Z
软件包许可：Yoti Face Capture Licence

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40getyoti/react-face-capture
原文对照：https://npmcn.com/package/%40getyoti/react-face-capture/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：16.5 MB，14 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：react \>=16\.14\.0 \<=18\.3\.1，react-dom \>=16\.14\.0 \<=18\.3\.1
- 首次发布：2020-12-17T14:10:18.220Z
- 最新版本发布：2026-10-28T14:57:17.548Z
- 近 30 天下载量：23135（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：42（近 12 个月 7 个）

## 中文简介

用于为 Yoti AI API 收集图片和数据的相片抓取模块

## 安装

```sh
npm install @getyoti/react-face-capture
```

也可以使用：`pnpm add @getyoti/react-face-capture`、`yarn add @getyoti/react-face-capture`、`bun add @getyoti/react-face-capture`

## README

# Yoti 面部抓取集成

本模块的目的是捕捉出一张相并还原输出图像.

## 变化

请检查一下 [变化](https://github.com/getyoti/web-fcm-demo/blob/main/docs/FCM-CHANGELOG.md) (c) 审查主要版本的发布变化、问题、修正和可能的中断变化.

## 采用依赖性的前提条件

### 同伴依赖关系

软件包取决于以下对等关系

```
"react": ">=16.14.0 <=18.3.1",
"react-dom": ">=16.14.0 <=18.3.1"
```

### 浏览器支持

| 浏览器 | 版本数 |
| --- | --- |
| 缩写( c) | 156 (中文(简体) ) |
| 铬 | 156,155,154,153 (中文(简体) ) |
| 边缘 | 155,154 (韩语) |
| 火花 | 158 157 156 155美元 |
| oos saf (日语) | 27.0,26.6,26.5 (韩语) |
| 萨法里 | 27,26.6,26.5,26.4 (中文(简体) ) |

第二,模块需要 `MediaDevices.getUserMedia()` 工作的时候。 当浏览器不支持时, 错误 `UNSUPPORTED_BROWSER` 将发送.

_注:iOS上的非Safari浏览器由于iOS的限制而得不到支持._

_注:边缘只在桌面版本中支持._

最后,一些设备在试图检测出相貌时可能会出现性能不佳. 这是因为基础库"TensorFlow.js"对于更古老的性能较差的设备来说仍然可能要求太高.

_说明: `iPhone 7` 与更近期的设备相比,老化的装入面部探测器模型需要更长的时间,在多数情况下,会从自動回落到手動取取模式. 如果此行为不可取, 作为整齐器您可以完全禁用手动抓取模式, 执行手动 CaptureFallback = false 。 注意,这可能会增加旧和低质量设备的载荷时间._

_注意: 有可能在 Firefox 中禁用图片映射特性 [其配置](https://support.mozilla.org/en-US/kb/turn-picture-picture-mode)。 。 。 ._

## 反应取相

### 安装依赖性

```
npm i @getyoti/react-face-capture -S
```

### 导入js和css

```
import FaceCapture from "@getyoti/react-face-capture"
```

### 复制资产

**资产** 不包括在 Javascript 捆绑。 要让组件正确工作, 您需要将库资产复制到 `./node_modules/@getyoti/react-face-capture/assets` 文件夹进入您的输出资产文件夹.

例如,在网络包装中,您可以使用插件 `copy-webpack-plugin` 以下列方式:

```js
new CopyPlugin({
  patterns: [
    {
      from: path.resolve(__dirname, './node_modules/@getyoti/react-face-capture/assets'),
      to: path.resolve(__dirname, './dist/assets'),
    },
  ],
});
```

### CSS 自定义

可以通过更改以下 CSS 属性来自定义样式 :

-   `--fcm-background-color` 设置背景颜色.
-   `--fcm-background-color-variant1` 背景颜色的备选案文1.
-   `--fcm-background-color-variant2` 背景颜色的备选案文2.
-   `--fcm-background-color-contrast` 用于对比元素如分隔符或对话框滚动条的颜色 .
-   `--fcm-button-color` 按钮所用的颜色 .
-   `--fcm-button-color-hover` 徘徊时按钮所用的颜色 .
-   `--fcm-button-color-press` 按下按钮时所用的颜色 .
-   `--fcm-text-color-primary` 主文本所用的颜色 .
-   `--fcm-text-color-secondary` 次要文本所用的颜色 .
-   `--fcm-font-family` 设置字体家族.
-   `--fcm-overlay-color` 设置覆盖的颜色和不透明.
-   `--fcm-frame-color-neutral` 设置相框的颜色.
-   `--fcm-frame-color-success` 设置相框的成功颜色.
-   `--fcm-frame-color-warning` 设置相框的警告颜色.
-   `--fcm-frame-color-invalid-manual` 设置手动模式无效图像用户反馈的面框颜色.
-   `--fcm-border-radius` 设定模块角的半径。 默认为 `0px` (平分数.
-   `--fcm-button-border-radius-bottom-left` 设置按钮的边框半径.
-   `--fcm-button-border-radius-bottom-right` 设置按钮的边框半径.
-   `--fcm-button-border-radius-top-right` 设置按钮的边框半径.
-   `--fcm-button-border-radius-top-left` 设置按钮的边框半径.
-   `--fcm-help-panel-border-radius-bottom-left` 设置帮助对话框的边框半径.
-   `--fcm-help-panel-border-radius-bottom-right` 设置帮助对话框的边框半径.
-   `--fcm-help-panel-border-radius-top-right` 设置帮助对话框的边框半径.
-   `--fcm-help-panel-border-radius-top-left` 设置帮助对话框的边框半径.
-   `--fcm-feedback-border-radius-bottom-left` 设置用户反馈的边框半径.
-   `--fcm-feedback-border-radius-bottom-right` 设置用户反馈的边框半径.
-   `--fcm-feedback-border-radius-top-right` 设置用户反馈的边框半径.
-   `--fcm-feedback-border-radius-top-left` 设置用户反馈的边框半径.
-   `--fcm-prompt-portrait-top` 设置使用肖像设备的用户反馈( 即时) 垂直偏移 `center` (建议百分比)。 默认值为 0.

2.6.0版的定制办法有所改变。 下列变量已贬值,并将在未来版本被删除:

-   `--fcm-primary-button-background-color`
    -   `--fcm-primary-button-background-color-hover`
-   `--fcm-primary-button-text-color`
-   `--fcm-secondary-button-background-color`
-   `--fcm-secondary-button-text-color`
    -   `--fcm-secondary-button-text-color-hover`
-   `--fcm-prompt-text-color`
-   `--fcm-prompt-background-color`

CSS 自定义属性必须使用 `:root` CSS选取器. 以下是一个例子:

```css
:root {
  --fcm-button-color: red;
}
```

> **说明:** 字体和颜色上的所有变化都由整形人负责,需要由整形人进行测试.

### 属性

| 属性名称 | 类型 | 默认 | 强制性 | 说明 |
| --- | --- | --- | --- | --- |
| 抓取方法 | 字符串 `manual/auto` | `auto` | \- 说吧 | 拍照的抓取方法:点击按钮或自动抓取. |
| 手动 Capture Fall Back 程序 | 布尔 | `true` | \- 说吧 | 单位 `auto` 捕获方法,允许使用 `manual` 抓取模式为倒置 。 只有在检测到性能差,通常是在很老的装置上,才会触发这种情况。 注:如果关闭此选项, 有些用户可能无法成功提交图像 . |
| 安全 | 布尔 | `true` | \- 说吧 | 使用 [安全模式](https://npmcn.com/package/%40getyoti/react-face-capture/#readme-secure-mode) |
| 客户端SdkId | 字符串 | \- 说吧 | 对\* | 确定你的YotiHub应用程序。 此值可以在 Hub 中找到, 在您的应用程序部分, 在密钥标签中找到 . |
| 成功时 | 函数( 载荷, 基数64PreviewImage) | \- 说吧 | 对 | 一旦结果( 负载) 完成, 便召回 。 当使用安全模式或非安全模式时,捕获内容会有所不同(见 [安全模式区域](https://npmcn.com/package/%40getyoti/react-face-capture/#readme-secure-mode)) (中文(简体) ). 第二个论点 `base64PreviewImage` 只有在 `returnPreviewImage` 设置为 `true`。 。 。 . |
| 错误 | 函数 | \- 说吧 | \- 说吧 | 出现错误时调用 。 参见我们目前支持的错误代码列表附录. |
| 准备能力 | 函数 | \- 说吧 | \- 说吧 | 当"面部抓取"准备取取影像(相机种子和面部扫描准备)时调用回电. |
| 手册背面 | 函数 | \- 说吧 | \- 说吧 | 当"Face Captal"从自动返回到手动抓取模式时调用回调. |
| 显示覆盖 | 布尔 | `true` | \- 说吧 | 可选使用面额覆盖. |
| 分辨率类型 | 字符串 `hd/full_hd` | `hd` | \- 说吧 | 图像解析限制传递到 `getUserMedia`如果 `multiframe` 实值 `true`,解析 捕获的图像将是 `HD` 而这个字段将被忽略. |
| 格式 | 字符串 `jpeg/png` | `jpeg` | \- 说吧 | 图像格式类型 。 若为 `multiframe` 实值 `true`,所捕获图像的格式将是 `jpeg` 而这个字段将被忽略. |
| 图像类型 | 字符串 `original/cropped` | `original` | \- 说吧 | 选择图像是原始的还是被裁剪,以便在API呼叫中处理图像时改进时间响应. 若为 `multiframe` 实值 `true`,图像类型将是 `original` 而这个字段将被忽略. |
| 质量类型 | 字符串 `high/medium/low` | `high` | \- 说吧 | 只设定jpeg格式图像的图像质量。 高 (1)-中 (0.96)-低 (0.90). 若为 `multiframe` 实值 `true`,捕获图像的质量将是 `high` 而这个字段将被忽略. |
| 语言 | 语言代码\*\* | `en` | \- 说吧 | 设置 Face 抓取语言的语言代码 . |
| a11y 注册模式 | 字符串 `assertive/polite` | `polite` | \- 说吧 | **已删除:将在下一期主要发布中删除.** 决定 [现场区域的礼貌环境](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions#live_regions) 用于读取屏幕阅读器用户的提示 |
| 显示初始指南 | 布尔 | `true` | \- 说吧 | 显示初始帮助引导. |
| 相机自动旋转 | 字符串 | `assets/face-capture/` | \- 说吧 | 面部检测资产所在的根 URL 。 见 [复制资产](https://npmcn.com/package/%40getyoti/react-face-capture/#readme-copy-assets) 资产配置. |
| 装入超时 | 数目 | 60 000毫秒( 秒) | \- 说吧 | 设定 Face 抓取将用来通过 `onError` 如果模块下载和加载模块需要时间太长,则调用。 Face Capture 会在通知后继续加载. |
| 显示帮助按钮 | 布尔 | `true` | \- 说吧 | 显示“ 获取帮助” 按钮 . |
| 自动加载 | 布尔 | `true` | \- 说吧 | 到期后自动续展会话. |
| 用户重试错误 | 布尔 | `true` | \- 说吧 | 允许用户在出错时多次重试. |
| 返回预览图像 | 布尔 | `false` | \- 说吧 | 提供所捕获的图像( E)`base64PreviewImage`)在 `onSuccess` 调用。 请注意,预览图像没有签名,因此只能用于用户反馈. 对于需要存储或使用实际图像的应用程序,我们建议设置 `encryptImage` 以假相报. |
| 加密图像 | 布尔 | `true` | \- 说吧 | 加密有效载荷参数中的图像 `onSuccess` 当它运行安全模式时调用. |
| 允许背景面 | 布尔 | `false` | \- 说吧 | 当图像被捕获时, 允许在背景中显示相片 。 当设定到时, Face 抓取会返回被剪切的图像, 并带主面 `true`如果 `multiframe` 实值 `true`,此字段将被忽略并当作 `false`说明: 这个功能是为零售终端设计的,不适合在线用户取相. |
| 面额选择方法 | 字符串 `center/area` | `center` | \- 说吧 | 定义主面可放放的地方,中心或图像的任何地方. 说明: 这个功能是为零售终端设计,不适合在线用户取相. 建议启用 `allowBackgroundFaces` 何时 `faceSelectionMethod` 设置为 `area`。 。 。 . |
| 数字平面 | 数目 | 页:1 | \- 说吧 | 确定用于稳定性检查的帧数 。 最低值为3,最高值为6. |
| 会话期限 | 数目 | \- 说吧 | \- 说吧 | 使会话在指定的毫秒后超时, 不论重复尝试的次数。 必须是至少3万(30s)和最多30万(5m). |
| 是相片卡美拉 _(实验性)_ | 布尔 | `false` | \- 说吧 | 定义 FCM 是否在 SCO( 自检出) 机器中适应带有肖像分辨率的相机流 。 这个属性不会旋转相机流,而是使模块适应肖像分辨率. 此地产仅用于上合机,不应用于手机集成. |
| 光度检查级别 | 字符串 `default/low/disabled` | `default` | \- 说吧 | 请指定FCM对光度检查的严格程度,以便捕获图像。 在对照明条件具有挑战性的情况下,可能有助于缓解捕获过程,但可以提高服务中的拒绝率。 说明: 这个功能是为零售终端设计,不适合在线用户取相. |
| 多边形 | 布尔 | `false` | \- 说吧 | 导致FCM收集了多个图像,提供了更多的安全. 这个特性只有在安全性活动时才起作用,如果不起作用,它就会被忽略. |
| 肖像画 | 字符串 `9/16|10/16` | `9/16` | \- 说吧 | 定义肖像模式的宽比. |

**(\*)** 此字段仅在使用安全模式时是强制的 。 (安全=真实)

**联合国** 支持当前语言 :

-   `en-GB`页:1
-   `ar-XN`阿拉伯文
-   `az-AZ`: 阿塞拜疆语
-   `bg-BG`: 保加利亚语
-   `bs-BA`波斯尼亚语
-   `cnr-ME`页:1
-   `cs-CZ`捷克语
-   `da-DK`: 丹麦语
-   `de-DE`: 德语
-   `el-GR`: 希腊语
-   `es`: 西班牙语(西班牙)\*\*\*
-   `es-ES`: 西班牙语(西班牙)
-   `es-419`: 西班牙语(拉丁美洲)
-   `et-EE`: 爱沙尼亚语
-   `fa-IR`: 波斯语
-   `fi-FI`:芬兰语
-   `fr-FR`法语
-   `he-IL`希伯来语:
-   `hi-IN`页:1
-   `hr-HR`: 克罗地亚
-   `hu-HU`: 匈牙利语
-   `hy-AM`: 亚美尼亚语
-   `id-ID`: 巴哈萨
-   `it-IT`: 意大利语
-   `ja-JP`: 日语
-   `ko-KR`韩文:
-   `lt-LT`立陶宛语
-   `lv-LV`: 拉脱维亚语
-   `mk-MK`马其顿语
-   `ms`: 马来语 (马来西亚) \*\*\*
-   `ms-MY`: 马来语 (马来西亚)
-   `ms-SG:` 马来语( 新加坡)
-   `nb-NO`: 挪威语
-   `nl-NL`: 荷兰语
-   `pl-PL`波兰语
-   `pt`页:1
-   `pt-BR`: 葡萄牙语( 巴西)
-   `pt-PT`: 葡萄牙语( 葡萄牙)
-   `ro-RO`: 罗马尼亚
-   `ru-RU`页:1
-   `sk-SK`斯洛伐克语
-   `sq-AL`阿尔巴尼亚语
-   `sr-RS`: 塞尔维亚语(焦耳字母)
-   `sr-Latn-RS`: 塞尔维亚语(拉丁文)
-   `sr-Latn-ME`黑山(别名: `cnr-ME`(中文(简体) )
-   `sv-SE`: 瑞典语
-   `th-TH`页:1
-   `tl-PH`: 塔加洛格语
-   `tr-TR`页:1
-   `uk-UA`乌克兰语
-   `ur-PK`: 乌尔都语
-   `vi-VN`: 越南语
-   `zh-CN`:中文 (简化)
-   `zh-TW`: 传统汉语 (台湾)

**页:1** 以 \*\*\* 为标记的语言代码被列出,以在倒置上进行分解. 它们与各自的区域变体完全相同.

#### 语言倒置

用于财产的机制 `language` 以避免在数值过错时出现问题。 示例:首先尝试精确匹配(es-es或es-ES,忽略大小写):

-   如果没有匹配,请通过去除区域部分(-es)来尝试主流(es).
-   如果没有主流,请尝试任何其他可用的es-\[地区\]兄弟姐妹(例:es-419).
-   如果没有区域兄弟姐妹,请使用默认语言:en.

#### 错误代码

| 错误代码 | 说明 |
| --- | --- |
| `NO_CAMERA` | 用户设备上未检测到相机 . |
| `GENERIC_CAMERA_ERROR` | 未定义相机出错 。 原因可以是: [各种](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia) 和不一致的浏览器. |
| `UNSUPPORTED_BROWSER` | 不支持用户的浏览器 。 这可能是因为缺少相机交互所需的API. `Note: Older Non-Safari browsers on iOS fall into this category.` |
| `NO_CAMERA_PERMISSION` | 用户拒绝了相机许可. |
| `OVERCONSTRAINED` | 相机的限制与现有的相机设备不相容. `Note: One recovery option could be to use hd resolution.` |
| `FACE_DETECTION_INIT_ERROR` | 面部检测失败 。 这通常意味着所需的模型资产在主机应用程序中缺失. |
| `INTERNAL_ERROR` | 这可能是由于编程出错,或者用户使用旧的不支持的浏览器. |
| `CAPTURE_LOAD_ERROR` | 无法装入安全模块 。 这通常意味着您的令牌没有更新,或者模块提供者存在出错. |
| `VIDEO_STREAM_INTERRUPTED` | 相机流突然停了下来. |
| `SECURE_SESSION_EXPIRED` | 安全会话已过期( 符号过期字段比当前时间长 ) . |
| `EXCEEDED_TIME_TO_LOAD` | 模块加载的时间比FaceCapture组件中设定的时间要长. _此错误不妨碍模块继续加载_它提醒整合者,以便他们能够决定给予用户更多的保证。 超时值可以通过更新 `loadTimeout` 选项,默认为60秒(60 000ms). |
| `VERSION_NO_LONGER_AVAILABLE` | 已无法使用所要求的 Face Capture 安全模块 。 注意FCM如果模块被贬值,将会在控制台上登录一个警告. |
| `INVALID_SECURE_CLIENT_SDK_ID` | 客户端SDK ID格式错误,没有包含在内部产品映射中,或者JWT的SDK与BE请求中包含的内部产品存在不匹配. |

错误代码可导入如下:

```js
import { ERROR_CODE } from '@getyoti/react-face-capture';
```

#### 安全模式

安全模式允许 [Yoti 后端( Y) 服务](https://developers.yoti.com/age-estimation/integration-guide) 以验证在客户端浏览器上 使用 Face Captrl 捕获的图像是否 以任何形式修改.

注意, Yoti Face Capture 的安全模式向 Yoti 请求 后端下载使用此选项的加密抓取包 图片并创建安全结果请求 。 安全的结果信息将 返回时 `onSuccess` 回调( c)`payload` 参数)。 这是信息 关于 _Yoti 后端服务_ 需要运行一个预测。 服务会的 如果返回错误,则返回错误 `payload` 已修改 :

```json
{
  "img": "<base64_img>",
  "secure": {
    "version": "<fcm_version>",
    "token": "<session_token>",
    "signature": "<result_signature>",
    "verification": "<verification_data>"
  }
}
```

`<fcm_version>` 是当前版本的FCM(嵌入于 模块)和 `<session_token>` 是请求生成的会话符号.

关于安全模式如何与服务器互动的更详细资料,请参见: [安全图像抓取](https://developers.yoti.com/age-estimation/secure-image-capture) 页 次.

> 添加了20秒的超时,以避免在网络连接差或无法使用时等待时间长.

##### 可能的问题

安全模式要求 Yoti 服务下载加密模块 因此,客户必须能够处理这些请求。 记住,如果 您的客户端使用任何机制来防止数据注入攻击或 像CSP这样的跨站点脚本 您需要允许 FCM 请求 .

##### 虚拟相机

安全模式探测到相机流源和欺诈相机硬件上的修改. 在这种情况下,它将返回 `UNTRUSTED_SECURE_SESSION` 调用 Yoti BE 服务时错误代码 .

##### 多边形

这个 `multiframe` 模式增加了一层额外的安全,以更好地防止注射攻击和其他形式的图像操纵. 它无缝运作,确保用户经验不受影响。 这需要 `secure` 模式将启用并增加生成的有效载荷的大小.

### 示例

```js
import FaceCapture from '@getyoti/react-face-capture';

export function App() {
  const onSuccess = (payload, base64PreviewImage) => console.log('Length = ', payload.img.length);
  const onError = (error) => console.log('Error =', error);

  return <FaceCapture returnPreviewImage onSuccess={onSuccess} onError={onError} />;
}
```

## 脸部抓取香草

对于没有React技术堆栈的工程,可以使用Face Capture vanilla版本. 当你在机器上安装库时, 它就位于文件夹内 `vanilla`。 。 。 .

将软件包添加到您的代码库并服务静态资产 :

### 1\. 服务包静态资产

```bash

/@getyoti/react-face-capture/vanilla/assets/face-capture/
/@getyoti/react-face-capture/vanilla/index.js
```

### 2\. 添加 face 抓取脚本

在您想要拥有 Face Capture 的页面中,添加 Face Capture 脚本和样式,比如下面的例子. `faceCaptureAssetsRootUrl` 是一个您可以用来指示提供神经网络文件的库的属性, 否则我们查找相对于页面位置的文件 `assets/face-capture/`。 。 。 .

### 3\. 捕捉变形相

我们的剧本可以让你访问 `Yoti.FaceCaptureModule.render` 您可以设置两个参数。 第一个参数是属性,在与反应的结合中使用的属性相同. 第二个参数是HTML DOM的参考,所以我们知道在哪里可以制取UI.

为了卸载该组件,强烈建议调用 `Yoti.FaceCaptureModule.unmount` 函数而不是破坏 HTML 元素,这可能导致一些问题或不当行为.

**索引.html**

```html
<script src="/@getyoti/react-face-capture/vanilla/index.js"></script>
<script>
  const props = {
    faceCaptureAssetsRootUrl: '/@getyoti/react-face-capture/vanilla/assets/face-capture/',
    onSuccess: (data) => {
      console.log('Length = ', data.img.length);
    },
    onError: (error) => {
      console.log('Error =', error);
    },
  };

  const fcm = Yoti.FaceCaptureModule.render(props, document.getElementById('face-capture-module-root'));

  function reload() {
    fcm.reload();
  }

  function unmount() {
    fcm.unmount();
  }
</script>

<div id="face-capture-module-root"></div>
```

## 调试 Yoti 面部抓取

出于安全考虑,Yoti Face Captright被用代码模糊技术保护.

这种保护既存在于安全模式中,也存在于非安全模式中,这使得通过在任意浏览器上使用开发工具来调试模块几乎是不可能的,因为应用程序会在工具菜单打开后崩溃或继续循环.

## 解决问题

### 下一个 JS

Face Capture 不支持服务器侧渲染 。 需要加载 动态 :

```jsx
import dynamic from 'next/dynamic';
const FaceCapture = dynamic(() => import('@getyoti/react-face-capture'), {
  ssr: false,
});

export default function CustomFCM(props) {
  return <FaceCapture {...props} />;
}
```

### 网络软件包

安全模式根据要求从服务器端装入安全javascript代码. 这个 Face 抓取使用注释 `/* webpackIgnore: true */` 命令以告诉网页包 无需在当地解决依赖性问题,因此本评论不能 在 webpack 为网页建立最后的 javascript 文件之前删除 应用.

### iOS 扭曲布局( 版本 < 2. 4. 0)

我们知道iOS设备上一个罕见的显示问题,它能使视频元素在 2. 4.0 之前的版本中出现扭曲. 刷新或再装入将解决这个问题,不应经常发生.

### 虚拟背景

相对于相机所捕获的原始图像的修改,如虚拟背景或其他类型的过滤器,也被认为是被操纵. 使用这些特性拍摄的相片将被拒绝 `UNTRUSTED_SECURE_SESSION`。 。 。 .

### 多帧模式使用

使用多帧模式时, 预测请求必须包含查询参数 `multiframe=true`。这是服务正确处理请求所需的。 如果Face Capture 的多帧设置与请求中的多帧查询参数不匹配,则回复总是 `UNTRUSTED_SECURE_SESSION`。 。 。 .

在启用此模式时, 确保Face Capture 配置和预测请求都对齐以避免出错 .

### 权限政策

在 iFrame 内运行 FCM 时,可能需要设置 [权限政策](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Permissions_Policy) 确保该系统如预期的那样运作.

FCM 的用途为: `camera` 财务报告和审定财务报表 `autoplay` 设置 `allow` iFrame属性 类似的东西.

```html
<iframe allow="autoplay *; camera *;" />
```

只允许 `camera` 财务报告和审定财务报表 `autoplay` 。无论主机文件的来源。 其他属性可以设置为 `none`。 。 。 .

请记住你需要反映 `<head>` 通过设置 HTML 文件 `<meta>` 标记带有与上述相同的权限政策字符串。 例如:

`<meta http-equiv="Permissions-Policy" content="autoplay=*, camera=*">`

## 常见问题

### @getyoti/react-face-capture 是什么？

用于为 Yoti AI API 收集图片和数据的相片抓取模块

### 如何安装 @getyoti/react-face-capture？

在项目目录运行 npm install @getyoti/react-face-capture，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16\.14\.0 \<=18\.3\.1）、react-dom（\>=16\.14\.0 \<=18\.3\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @getyoti/react-face-capture 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @getyoti/react-face-capture 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @getyoti/react-face-capture 可以商用吗？

@getyoti/react-face-capture 使用 Yoti Face Capture Licence 许可。声明的许可为 Yoti Face Capture Licence，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @getyoti/react-face-capture 的下载量有多少？

根据 npm 官方下载统计，@getyoti/react-face-capture 在 2026/10/17 – 2026/11/15 这 30 天内被下载 23,135 次，日均约 771 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @getyoti/react-face-capture 还在维护吗？

最新版本 2\.11\.0 发布于 2026/10/28（18 天前）；至今共发布 42 个版本，其中过去 12 个月发布了 7 个；首次发布于 2020/12/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

