Web FCM

AI Tools

If you have integrated the age estimation and liveness API, we strongly recommend adding our face capture module to enhance your results. When deployed in a web application, Yoti optionally provides a JavaScript Face Capture Module (FCM) that uses the webcam to capture an image of the user, which can be sent to the Yoti services backend for processing.

There are 2 steps to follow to integrate the face capture module:

Install the package
Integrate the package.

This service has specific image quality requirements.

Secure Image Capture (SICAP)

By integrating our Web FCM, you will benefit from our proprietary SICAP technology. This approach effectively prevents injection attacks, as each image capture is signed and verified by our backend. It also blocks the use of virtual cameras and hijacking of HTTP requests.

Install the package

Yoti currently supports:

React JS (Next JS)
Javascript

React JS

Install the dependency.

npm i @getyoti/react-face-capture -S import FaceCapture from "@getyoti/react-face-capture"

yarn add @getyoti/react-face-capture import FaceCapture from "@getyoti/react-face-capture"

Next.JS implementation

To ensure the Yoti Face Capture Module functions correctly, it must be excluded from minification within your Next.js configuration (next.config.js or next.config.mjs).

The package depends on the following peer dependencies:

"react": ">=16.14.0 <=18.2.0", "react-dom": ">=16.14.0 <=18.2.0"

The package supports the following browser versions:

Browser	Versions
Android Chrome	139
Google Chrome	140, 139, 138, 137
Microsoft Edge (Desktop only)	140, 139
Mozilla Firefox	142, 141, 140, 139
iOS Safari	18.5-18.6, 18.4, 18.3
Apple Safari	18.5-18.6, 18.4, 18.3, 18.2

Assets are not included in the javascript bundle. To have the components work correctly, you will need to copy library assets from @getyoti/react-face-capture/assets folder into your assets folder.

For instance, in WebPack, you can use the plugin copy-webpack-plugin in the following way:

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

JavaScript (vanilla)

For projects without a React tech stack, you can use the Face Capture vanilla version. When you install the library on your machine, It's located inside the folder vanilla.

Add the package to your codebase and serve the static assets:

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

Inside the page you want to have Face Capture, add Face Capture scripts and styles like in the example below. faceCaptureAssetsRootUrl is a property you can use to instruct the library where neural net files are served otherwise we look for the files relative to the page location assets/face-capture/.

Our scripts will give you access to Yoti.FaceCaptureModule.render where you can set 2 parameters. The first parameter is the properties, the same ones used in the integration with react. The second parameter is a reference to html DOM, allowing you to decide where to render the UI.

In order to unmount the component, it is highly recommended to call the Yoti.FaceCaptureModule.unmount function instead of destroying the html element, which could lead to some issues or misbehaviour.

CSS Customization

It is possible to customise the style by changing the following CSS properties:

CSS Properties	Description
`--fcm-background-color`	Sets the background color.
`--fcm-background-color-variant1`	Variant 1 of the background color.
`--fcm-background-color-variant2`	Variant 2 of the background color.
`--fcm-background-color-contrast`	Color used for contrast elements like separators or the dialog scrollbar.
`--fcm-button-color`	Color used for the buttons.
`--fcm-button-color-hover`	Color used for the buttons when hovered.
`--fcm-button-color-press`	Color used for the buttons when pressed.
`--fcm-text-color-primary`	Color used for the primary text.
`--fcm-text-color-secondary`	Color used for the secondary text.
`--fcm-font-family`	Sets the font family.
`--fcm-overlay-color`	Sets the color and opacity of the overlay.
`--fcm-frame-color-neutral`	Sets the color of the face frame.
`--fcm-frame-color-success`	Sets the success color of the face frame.
`--fcm-frame-color-warning`	Sets the warning color of the face frame.
`--fcm-frame-color-invalid-manual`	Sets the color of the face frame for manual mode invalid image feedback.

The CSS custom properties must be defined using the :root CSS selector. Here is an example:

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

Example code

Below is the full sample code of FCM integration

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 clientSdkId={'<YOUR_SDK_ID>'} returnPreviewImage={true} onSuccess={onSuccess} onError={onError} />; }

// The Face Capture does not support server side rendering. // It needs to be loaded dynamically. import dynamic from 'next/dynamic'; const FaceCapture = dynamic(() => import('@getyoti/react-face-capture'), { ssr: false, }); export default function CustomFCM(props) { return <FaceCapture {...props} />; }

Web demo

React web app example

Properties

Property	Type	Default	Description	Required
onSuccess	Function(payload, base64PreviewImage)		Callback called once the result (payload) is complete. The content of capture will vary when using secure or non-secure mode. The second argument `base64PreviewImage` will only be provided if `returnPreviewImage` is set to `true`.	✅
clientSdkId	String		Identifies your Yoti Hub application. This value can be found in the Hub, within your application section, in the keys tab.	✅ *
captureMethod	String `manual/auto`	`auto`	The way you capture the photo, either with the button of auto-capture.	❌
secure	Boolean	`true`	Use the secure mode	❌
onError	Function		Callback called when there is an error. See Appendix for the list of error codes we currently support.	❌
onReadyForCapture	Function		Callback called when the Face Capture is ready to take images (camera feed and face scan are ready).	❌
showOverlay	Boolean	`true`	Optional use of the face overlay.	❌
resolutionType	String `hd/full_hd`	`hd`	Image resolution constraints passed to `getUserMedia`. If `multiframe` is `true`, the resolution of the captured image will be `HD` and this field will be ignored.	❌
format	String `jpeg/png`	`jpeg`	Image format type. If `multiframe` is `true`, the format of the captured image will be `jpeg` and this field will be ignored.	❌
imageType	String `original/cropped`	`original`	Selects if the image will be the original or it will be cropped in order to improve the timing response when processing the image in the API call. If `multiframe` is `true`, the image type will be `original` and this field will be ignored.	❌
qualityType	String `high/medium/low`	`high`	Sets the image quality of jpeg format images only. High (1) - Medium (0.96) - Low (0.90). If `multiframe` is `true`, the quality of the captured image will be `high` and this field will be ignored.	❌
a11yLiveRegionMode	String `assertive/polite`	`polite`	DEPRECATED: will be removed in the next major release. Determines the politeness setting of the live region used to read out prompts for screen reader users	❌
faceCaptureAssetsRootUrl	String	`assets/face-capture/`	Root url where the face detection assets are located. See copy assets section for assets configuration.	❌
loadTimeout	Number	60000 milliseconds	Sets the time (in ms) the Face Capture will use to notify through the `onError` callback if the module takes too long to download and load the module. The Face Capture will keep loading after the notification.	❌
showGetHelpButton	Boolean	`true`	Show the Get Help button.	❌
showInitialGuidance	Boolean	`true`	Show the initial help guidance.	❌
autoSessionReload	Boolean	`true`	Automatically renews sessions after they expire.	❌
userRetryError	Boolean	`true`	Gives the possibility to users to retry several times when an error occurs.	❌
returnPreviewImage	Boolean	`false`	Provide the image captured (`base64PreviewImage`) in the `onSuccess` callback. Please note that the preview image is not signed, so it should only be used for user feedback. For applications that need to store or use the actual image, we recommend setting `encryptImage` to false.	❌
encryptImage	Boolean	`true`	Encrypt the image inside the payload argument on the `onSuccess` callback when it runs the secure mode.	❌
allowBackgroundFaces	Boolean	`false`	Allows faces to be present in the background when the image is being captured. The Face Capture will return a cropped image with the main face when set to `true`. If `multiframe` is `true`, this field will be ignored and treated as `false`. Note: This feature is designed for retail terminals and is unsuitable for online users' face capture.	❌
faceSelectionMethod	String `center/area`	`center`	Defines where the main face can be placed, in the center or anywhere in the image. Note: This feature is designed for retail terminals and unsuitable for online user's face capture. It is recommend to enable `allowBackgroundFaces` when `faceSelectionMethod` is set to `area`.	❌
numStableFrames	Number	4	Determines how many frames are used for the stability check. The minimum value is 3 and the maximum is 6.	❌
sessionDuration	Number		Causes the session to time out after the specified number of milliseconds, regardless of number of retry attempts taken. Must be at least 30,000 (30s) and at most 300,000 (5m).	❌
isScoPortraitCamera (experimental)	Boolean	`false`	Defines if the FCM should adapt to a camera stream with portrait resolution in a SCO (self-checkout) machine. This property won't rotate your camera stream but adapt the module to a portrait resolution. This property is meant for SCO machines only and shouldn't be used on mobile phone integrations.	❌
luminosityCheckLevel	String `default/low/disabled`	`default`	Specify how strict the luminosity check should be for the FCM to capture an image. It may be helpful to ease the capture process in challenging lighting conditions but could increase the rejection rate in the service. Note: This feature is designed for retail terminals and unsuitable for online user's face capture.	❌
multiframe	Boolean	`false`	Causes the FCM to collect more than one image, providing more security. This feature only works when secure is active, if not it will be ignored.	❌
language	String (refer to the Language Code list)	`en`	The language code to set the language of the feedback messages	❌

Language code list

Code	Language	Code	Language	Code	Language
`en-GB`	English	`hi-IN`	Hindi	`pt-PT`	Portuguese (Portugal)
`ar-XN`	Arabic	`hr-HR`	Croatian	`ro-RO`	Romanian
`bg-BG`	Bulgarian	`hu-HU`	Hungarian	`ru-RU`	Russian
`bs-BA`	Bosnian	`hy-AM`	Armenian	`sk-SK`	Slovak
`cs-CZ`	Czech	`id-ID`	Bahasa	`sr-RS`	Serbian (Cyrillic script)
`da-DK`	Danish	`it-IT`	Italian	`sr-Latn-RS`	Serbian (Latin script)
`de-DE`	German	`ja-JP`	Japanese	`sv-SE`	Swedish
`el-GR`	Greek	`ko-KR`	Korean	`th-TH`	th-TH
`es`	Spanish (Spain) **	`lt-LT`	Lithuanian	`tl-PH`	Tagalog
`es-ES`	Spanish (Spain)	`lv-LV`	Latvian	`tr-TR`	Turkish
`es-419`	Spanish (Latin America)	`ms-MY`	Malay	`uk-UA`	Ukrainian
`et-EE`	Estonian	`nb-NO`	Norwegian	`ur-PK`	Urdu
`fa-IR`	Persian	`nl-NL`	Dutch	`vi-VN`	Vietnamese
`fi-FI`	Finnish	`pl-PL`	Polish	`zh-CN`	Chinese (Simplified)
`fr-FR`	French	`pt`	Portuguese (Portugal) **
`he-IL`	Hebrew	`pt-BR`	Portuguese (Brazil)

(*) This field is only mandatory when using the secure mode. (secure = true)

()** Language codes marked with *** are listed for disambiguation purposes on the fallback.

Language fallback

A mechanism used for the property language to avoid issues when the value passed is wrong. Example: first try exact match (es-es or es-ES , ignore case):

If there is no match, try the mainstream es , by removing the region part -es .
If there is no mainstream, try any other available es-[region] sibling (example: es-419 ).
If there is no regional sibling, use the default language: en .

Error codes

Error Code	Description
`NO_CAMERA`	No camera detected on the user’s device.
`GENERIC_CAMERA_ERROR`	Undefined camera error. The reasons can be various and inconsistent across browsers.
`UNSUPPORTED_BROWSER`	The user’s browser is not supported. This could be because the API needed for the camera interaction is missing. `Note: Older Non-Safari browsers on iOS fall into this category.`
`NO_CAMERA_PERMISSION`	The user rejected the camera permission.
`OVERCONSTRAINED`	The camera constraints are not compatible with available camera devices. `Note: One recovery option could be to use hd resolution.`
`FACE_DETECTION_INIT_ERROR`	The face detection has failed to initialise. This usually means the required model assets are missing from the host application.
`INTERNAL_ERROR`	This can be due to a programming error, or the user using an old unsupported browser.
`CAPTURE_LOAD_ERROR`	The secure module could not be loaded. This usually means your token is not updated, or there is an error on the module provider.
`VIDEO_STREAM_INTERRUPTED`	The camera stream has stopped unexpectedly.
`SECURE_SESSION_EXPIRED`	The secure session has expired (the token expire field is older than the current time).
`EXCEEDED_TIME_TO_LOAD`	The module is taking longer than the time set in the FaceCapture component to load. This error does not prevent the module from continuing to load. It alerts the integrator so they can decide to give additional reassurance to their users. The timeout value can be changed by updating the `loadTimeout` option, which defaults to 60 seconds (60000ms).
`VERSION_NO_LONGER_AVAILABLE`	The requested Face Capture secure module is no longer available. Note that the FCM will log a warning in the console if the module was deprecated.
`INVALID_SECURE_CLIENT_SDK_ID`	The client SDK ID has a wrong format, it isn't included on the internal product mapping or there is a mismatch between the SDK from the JWT and the one related to the internal product contained in the BE request.

Last updated on

Was this page helpful?