@getyoti/react-face-capture

Yoti Face capture integration

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

Pre-requisite to adopt the dependency

Peer dependencies

The package depends on the following peer dependencies

"react": ">=16.12.0 <18",
"react-dom": ">=16.12.0 <18"

Browser support

Browser	Versions
and_chr	98
chrome	98,97,96,95
edge	98,97
firefox	97,96,95,94
ios_saf	15.2-15.3,15.0-15.1,14.5-14.8
safari	15.2-15.3,15.1,15,14.1

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.

React face capture module

Install dependency

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

import js and css

import FaceCapture from "@getyoti/react-face-capture"
import "@getyoti/react-face-capture/index.css"

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 @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([
  {
    from: path.resolve(__dirname, './node_modules/@getyoti/react-face-capture/assets'),
    to: path.resolve(__dirname, './assets')
  }
]),

Props

Property name	Type	Default	Mand	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.
countdownMode	String only_desktop/only_mobile/never/always	never	-	Indicates when the countdown will be used. Note: It's only used if captureMethod is set to manual.
secure	Boolean	false	-	If true, the face capture module will use the secure mode
onSuccess	Function({ img, secure })	-	Y	Callback called once the result (capture) is complete. The field secure is only returned in secure mode (See secure mode section)
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 module is ready to take images (Video 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	-	Image format type.
CustomManualButton	Function	simple button	-	Custom UI of the manual capture button. It uses onClick and disabled as props.
CustomConsentButton	Function	simple button	-	Custom UI of the consent button. It uses onClick and disabled as props.
imageType	String original/cropped	original	-	imageType select 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 language of the feedback messages.
a11yLiveRegionMode	String assertive/polite	polite	-	Determines the politeness setting of the live region used to read out prompts for screen reader users
isConsentRequired	Boolean	false	-	Makes sure that the user gives consent to the tool to analyse their face. If it is true, a button will appear on the bottom section of the module, asking the user for their consent, and not analysing the user face until the consent is given. After this, the button disappears.
faceCaptureAssetsRootUrl	string	assets/face-capture/	-	Root url where the face detection assets are located. See copy assets section for assets configuration.

(*) Current languages supported:

• en: English
• ar: Arabic
• cs: Czech
• da: Danish
• de: German
• es: Spanish (Spain)
• es-419: Spanish (Latin America)
• et: Estonian
• fi: Finnish
• fr: French
• he: Hebrew
• hi: Hindi
• hy: Armenian
• id: Bahasa
• it: Italian
• ja: Japanese
• ko: Korean
• lt: Lithuanian
• lv: Latvian
• ms: Malay
• nb: Norwegian
• nl: Dutch
• pl: Polish
• pt: Portuguese
• ro: Romanian
• ru: Russian
• sv: Swedish
• th: Thai
• tr: Turkish
• uk: Ukranian
• ur: Urdu
• vi: Vietnamese

Language fallback

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

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

Supported error codes

Error code	Description
NO_CAMERA	No camera detected on the user’s device
GENERIC_CAMERA_ERROR	Other camera error. The reasons can be various, and inconsistent across browsers. The complete error is logged in the user’s browser console.
UNSUPPORTED_BROWSER	The user’s browser is not supported, because the API needed for camera interaction is missing. Note: Older Non-Safari browsers on iOS also fall into this category.
NO_CAMERA_PERMISSION	The user rejected the camera permission
OVERCONSTRAINED	The camera constraints are not compatible with any camera device. Note: One recovery option is to lower the widthMinConstraint value.
FACE_DETECTION_INIT_ERROR	The face detection has failed to initialise. This usually means that the required model assets are missing from the host application.
INTERNAL_ERROR	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.

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 verifying 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 will request Yoti back-end in order to download the encrypted capture package that takes the photos and create the secure result request. The secure result information will be returned in onSuccess callback:

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

The flow for the secure mode is the following:

• Request for a session -> (GET) https://api.yoti.com/ai/sm/v1/secure-fcm/<version>/token
• Request for the encrypted javascript module -> (GET) https://api.yoti.com/ai/sm/v1/secure-fcm/<version>/module?s=<token>

Where <version> is the current version of the FCM (It is embedded in the module) and the <token> is the session token the first request returns.

Possible issues

The secure mode requests Yoti back-end in order to download the encrypted module on demand so the front-end must be able to handle that requests. Keep in mind if your front-end uses any mechanism to prevent data injection attacks or cross-site scripting like SCP you will need to allow the FCM requests.

Example

import FaceCapture from '@getyoti/react-face-capture';
import '@getyoti/react-face-capture/index.css';

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

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

Face capture module vanilla

If you do not have 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 in 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.css
/@getyoti/react-face-capture/vanilla/index.js

2. Add Face capture script and style

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

3. Render face capture

Our scripts will give you access to Yoti.FaceCaptureModule.render you can pass 2 parameters, first parameters are the props and are the same used in react integration and second parameter you need a html DOM reference 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, as this could lead to some issues or misbehavior.

index.html

<link href="/@getyoti/react-face-capture/vanilla/index.css" />
<script src="/@getyoti/react-face-capture/vanilla/index.js" />
<script>
  const props = {
    faceCaptureAssetsRootUrl: '/@getyoti/react-face-capture/vanilla/assets/';
  };

  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>

CHANGELOG

CHANGELOG file.