Yoti Face Capture integration

The purpose of this module is to capture a face and return the output image.

CHANGELOG

Please check the CHANGELOG to review release changes, issues, fixes, and possible breaking changes on Major releases.

Pre-requisite to adopt the dependency

Peer dependencies

The package depends on the following peer dependencies

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

Browser support

| Browser | Versions | | ------- | ------------------- | | and_chr | 128 | | chrome | 129,128,127,126 | | edge | 128,127 | | firefox | 130,129,128,127 | | ios_saf | 18.0,17.6,17.5 | | safari | 18.0,17.6,17.5,17.4 |

Secondly, the module needs MediaDevices.getUserMedia() to work. When this isn't supported by the browser, the error UNSUPPORTED_BROWSER will be sent.

Note: Non-Safari browsers on iOS are not supported because of an iOS limitation.

Note: Edge is only supported on desktop versions.

Finally, some devices might experience poor performance when attempting to detect a face. This is because the underlying library TensorFlow.js can still be too demanding for older less performant devices.

Note: iPhone 7 and older will take a longer time to load the face detector model than more recent devices, and in most cases, will fall back from auto to manual capture mode. If this behaviour is not desired, as an integrator you could disable the manual capture mode altogether, implementing manualCaptureFallback = false. Note, this could increase the load time for old and low-quality devices.

Note: It is possible to disable the picture-in-picture feature for Firefox in its configuration.

React Face Capture

Install dependency

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

Import js and css

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

Copy assets

Assets are not included in the javascript bundle. To have the components to work correctly, you will need to copy library assets from ./node_modules/@getyoti/react-face-capture/assets folder into your output 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'),
    },
  ],
});

CSS Customization

Now, it is possible to customize the style by changing the following CSS properties:

• --fcm-primary-button-background-color changes the background color in primary buttons (Take picture, Try again, ... ).
  • --fcm-primary-button-background-color-hover changes the background color in primary buttons (Take picture, Try again, ... ) when is hovered.
• --fcm-primary-button-text-color changes the text color in primary buttons (Take picture, Try again, ... ).
• --fcm-secondary-button-background-color changes the background color in secondary buttons (Get help).
• --fcm-secondary-button-text-color changes the text color in secondary buttons (Get help).
  • --fcm-secondary-button-text-color-hover changes the text color in secondary buttons (Get help) when the button is hovered.
• --fcm-font-family sets the font family.
• --fcm-prompt-text-color changes the text color in the prompt.
• --fcm-prompt-background-color sets the background color in the message prompt.

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

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

Note: We do not recommend changing these css properties, all changes on the font and colors are under the integrator's responsibility and need to be tested by the integrator. In addition, we can't guarantee external customizations support on new versions of the library

Properties

| Property name | Type | Default | Mandatory | Description | | ------------------------------------ | ------------------------------------- | ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | captureMethod | String manual/auto | auto | - | Capture method to take the photo: by clicking a button or auto-capture. | | manualCaptureFallback | Boolean | true | - | In auto capture method, allow the use of manual capture mode as fallback. This would be triggered only when low performance conditions are detected, usually on very old devices. NOTE: If this option is turned off, some users might not be able to successfully submit an image. | | secure | Boolean | true | - | Use the secure mode | | clientSdkId | String | - | Yes* | Identifies your Yoti Hub application. This value can be found in the Hub, within your application section, in the keys tab. | | onSuccess | Function(payload, base64PreviewImage) | - | Yes | Callback called once the result (payload) is complete. The content of capture will vary when using secure or non-secure mode (See secure mode section). The second argument base64PreviewImage will only be provided if returnPreviewImage is set to true. | | 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. | | format | String jpeg/png | jpeg | - | Image format type. | | 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. | | qualityType | String high/medium/low | high | - | Sets the image quality of jpeg format images only. High (1) - Medium (0.96) - Low (0.90). | | language | Language code ** | en | - | The language code to set the Face Capture language. | | a11yLiveRegionMode | String assertive/polite | polite | - | Determines the politeness setting of the live region used to read out prompts for screen reader users | | showInitialGuidance | Boolean | true | - | Show the initial help guidance. | | faceCaptureAssetsRootUrl | String | assets/face-capture/ | - | Root url where the face detection assets are located. See copy assets section for assets configuration. | | loadTimeout | Number | 15000 milliseconds | - | Sets the time (ms) the Face Capture will use to notify through the onError callback about downloading taking too long. The Face Capture will keep downloading after the notification. | | showGetHelpButton | Boolean | true | - | Show the Get Help button. | | 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. | | 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. Note: This feature is designed for retail terminals and unsuitable for online user's 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. | | 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. |

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

(**) Current languages supported:

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

(***) Language codes marked with *** are listed for disambiguation purposes on the fallback. They are exactly the same as their respective regional variants.

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 more than the time set in the FaceCapture component to load. The property to change that value is loadTimeout which by default is 15 seconds. | | 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. |

The error codes can be imported as follow:

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

Secure mode

The Secure mode allows Yoti back-end service to verify that the image captured on the client-side browser with the FCM hasn't been modified in any form. Note, the secure mode of Yoti FCM makes a request to Yoti back-end to download the encrypted capture package that takes the photo and create the secure result request. The secure result information will be returned in onSuccess callback (payload argument). It is the information that the Yoti back-end service needs to run a prediction. The service will return an error if the payload is modified:

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

<fcm_version> is the current version of FCM (embedded in the module) and <session_token> is the session token generated from the request.

Possible issues

The secure mode requests Yoti services to download the encrypted module on demand, therefore the client must be able to handle those requests. Keep in mind if your client uses any mechanism to prevent data injection attacks or cross-site scripting like CSP you will need to allow the FCM requests.

Virtual cameras

The secure mode detects modifications on the camera stream source and fraudulent camera hardware. In these scenarios, it will return an UNTRUSTED_SECURE_SESSION error code when calling the Yoti BE services.

Example

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

Face Capture 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:

1. Serve package static assets

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

2. Add Face Capture script

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

3. Render 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, so we know where we can 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.

index.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>

Debugging Yoti Face Capture

Yoti Face Capture is protected with code obfuscation techniques for security reasons.

This protection is present in both secure and non-secure modes and it makes it almost impossible to debug the module by using development tools on any browser, as the application will crash or keep looping right after the tool menu is opened.

Troubleshooting

NextJS

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

Webpack

The secure mode loads secure javascript code from server side on demand. The Face Capture uses the comment /* webpackIgnore: true */ order to tell webpack that it does not need to resolve the dependency locally so this comment cannot be removed before webpack builds the final javascript files for the web application.

iOS distorted layout (version < 2.4.0)

We are aware of a rare display issue on iOS devices which can make the video element appear distorted in versions prior to 2.4.0. Refreshing or reloading will resolve this, and it should not happen often.