@getyoti/react-face-capture

中文文档
2.11.0发布于 2026/10/28Yoti Face Capture LicenceTypeScriptCommonJS近 30 天下载 2.3万

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

中文使用文档
文档目录23 节
  1. 变化
  2. 采用依赖性的前提条件
  3. 同伴依赖关系
  4. 浏览器支持
  5. 反应取相
  6. 安装依赖性
  7. 导入js和css
  8. 复制资产
  9. CSS 自定义
  10. 属性
  11. 示例
  12. 脸部抓取香草
  13. 1. 服务包静态资产
  14. 2. 添加 face 抓取脚本
  15. 3. 捕捉变形相
  16. 调试 Yoti 面部抓取
  17. 解决问题
  18. 下一个 JS
  19. 网络软件包
  20. iOS 扭曲布局( 版本 < 2. 4. 0)
  21. 虚拟背景
  22. 多帧模式使用
  23. 权限政策

Yoti 面部抓取集成

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

变化

请检查一下 变化 (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 中禁用图片映射特性 其配置。 。 。 .

反应取相

安装依赖性

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 以下列方式:

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选取器. 以下是一个例子:

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

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

属性

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

错误代码可导入如下:

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

安全模式

安全模式允许 Yoti 后端( Y) 服务 以验证在客户端浏览器上 使用 Face Captrl 捕获的图像是否 以任何形式修改.

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

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

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

关于安全模式如何与服务器互动的更详细资料,请参见: 安全图像抓取 页 次.

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

可能的问题

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

虚拟相机

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

多边形

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

示例

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. 服务包静态资产


/@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

<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 不支持服务器侧渲染 。 需要加载 动态 :

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 时,可能需要设置 权限政策 确保该系统如预期的那样运作.

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

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

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

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

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

版本与发布记录

@getyoti/react-face-capture 共发布 42 个版本,首次发布于 2020/12/17;过去 12 个月发布了 7 个版本。

版本发布日期距今
2.11.0latest2026/10/2818 天前
2.10.12026/10/131 个月前
2.10.02026/09/251 个月前
2.9.22026/06/045 个月前
2.9.12026/05/146 个月前
2.9.02026/03/277 个月前

关于 @getyoti/react-face-capture 的常见问题

@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 和提交记录判断。