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 recommends using our Face Capture Module (FCM), which uses the webcam to capture a user image that 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 , next.config.ts or next.config.mjs).

For Next.js with Turbopack, minification can be disabled with the turbopackMinify.

The package depends on the following peer dependencies:

"react": ">=16.14.0 <=18.3.1",

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

The package supports the following browser versions:

Browser	Versions
Android Chrome	151
Google Chrome	151, 150, 149, 148
Microsoft Edge (Desktop only)	151, 150
Mozilla Firefox	154, 153, 152, 151
iOS Safari	26.6, 26.5, 26.4
Apple Safari	26.6, 26.5, 26.4, 26.3

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.

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.

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>

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.
`--fcm-button-border-radius-bottom-left`	Sets the bottom-left border radius of the buttons.
`--fcm-button-border-radius-bottom-right`	Sets the bottom-right border radius of the buttons.
`--fcm-button-border-radius-top-right`	Sets the top-right border radius of the buttons.
`--fcm-button-border-radius-top-left`	Sets the top-left border radius of the buttons.
`--fcm-help-panel-border-radius-bottom-left`	Sets the bottom-left border radius of the help dialogue.
`--fcm-help-panel-border-radius-bottom-right`	Sets the bottom-right border radius of the help dialogue.
`--fcm-help-panel-border-radius-top-right`	Sets the top-right border radius of the help dialogue.
`--fcm-help-panel-border-radius-top-left`	Sets the top-left border radius of the help dialogue.
`--fcm-feedback-border-radius-bottom-left`	Sets the bottom-left border radius of the user feedback.
`--fcm-feedback-border-radius-bottom-right`	Sets the bottom-right border radius of the user feedback.
`--fcm-feedback-border-radius-top-right`	Sets the top-right border radius of the user feedback.
`--fcm-feedback-border-radius-top-left`	Sets the top-left border radius of the user feedback.
`--fcm-prompt-portrait-top`	Sets the user feedback (prompt) vertical offset for portrait devices when `faceSelectionMethod` is set to `center` (percentage recommended). The default value is 0. More details can be found in the Properties section.

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} />;

}

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>

Web demo

React web app example

Properties

Property	Type	Default	Description	Required
onSuccess	Function(payload, base64PreviewImage)		This callback function is triggered once the result (payload) is complete. The second argument `base64PreviewImage` will only be provided if `returnPreviewImage` is set to `true`.	✅
clientSdkId	String		Your SDK ID that is obtained from the Yoti Hub.	✅
secure	Boolean	`true`
captureMethod	String `manual/auto`	`auto`	The way you capture the photo. `Auto` - auto-capture `Manual` - capture with a button-click	❌
onError	Function		This callback function is triggered when there is an error.	❌
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 the multiframe parameter is set to `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 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.	❌
faceCaptureAssetsRootUrl	String	`assets/face-capture/`	Root url where the face detection assets are located	❌
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 users the possibility 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 in secure mode.	❌
allowBackgroundFaces	Boolean	`false`	This feature is designed for retail terminals only and is unsuitable for web FCM integration.	❌
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 is unsuitable for online users' face capture. It is recommended to enable `allowBackgroundFaces` when `faceSelectionMethod` is set to `area`.	❌
numStableFrames	Number	4	Determines how many frames are used for the stability check. Minimum: 3 Maximum: 6.	❌
sessionDuration	Number		Causes the session to time out after the specified number of milliseconds, regardless of the number of retry attempts taken. Minimum: 30,000 (30s) Maximum: 300,000 (5m)	❌
multiframe	Boolean	`false`	Causes the FCM to collect more than one image, providing more security. This feature only works when secure mode is active; if not, it will be ignored.	❌
language	String (refer to the Language Code list below)	`en`	The language code to set the language of the feedback messages	❌
luminosityCheckLevel	String `default/low/disabled`	`default`	Specify how strict the luminosity check should be for the FCM to capture an image. 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.	❌

Language code list

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

Note: 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.` The module needs `MediaDevices.getUserMedia()` to work. When this isn't supported by the browser, the error `UNSUPPORTED_BROWSER` will be sent.
`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?