@getyoti/react-native-yoti-face-capture v3.0.1

Yoti Face Capture for React Native

An easy to use face detection component for React Native from Yoti. Face detection is performed with the front-facing camera. The captured frames get analyzed by the library. The result is an optimised cropped image of the captured face.

The library leverages Google ML Kit for face detection on Android, while the iOS implementation uses Apple’s Vision library.

Installation

yarn add @getyoti/react-native-yoti-face-capture

Navigate to your iOS folder and install pods with:

pod install

React Native's autolinking will handle the rest of the native configuration. Should autolinking fail, consult the troubleshooting instructions.

Install the library with:

yarn add @getyoti/react-native-yoti-face-capture

Link the library:

react-native link @getyoti/react-native-yoti-face-capture

If you're using CocoaPods, navigate to your ios and update your Podfile:

  pod 'Folly', :podspec => '../node_modules/react-native/third-party-podspecs/Folly.podspec'
+  `pod 'react-native-yoti-face-capture', :path => '../node_modules/react-native-yoti-face-capture/react-native-yoti-face-capture.podspec'`
end

You may then run:

pod install

Android Configuration

• Requires Android API Level 21+

The library employs the bundled version approach approach for the AI models.

iOS Configuration

• Requres iOS 12.0+
• Requres Swift 5.3+

Make sure you've installed and are running the latest version of Cocoapods. Add the use_frameworks! declaration to your Podfile and run pod install from the ios directory:

platform :ios, '12.0'

target 'TargetName' do
  use_frameworks!
  ...
end

Usage

Camera access is required in order for the face detection to work. If your application does not request camera access from the user already, you may consider an in-built approach such as PermissionsAndroid. Alternatively, you may use community libraries like React Native Permissions.

import React, {PixelRatio, useRef, useWindowDimensions} from 'react';
// Image quality options
import YotiFaceCapture, {
    IMAGE_QUALITY_LOW,
    IMAGE_QUALITY_MEDIUM,
    IMAGE_QUALITY_HIGH
} from "react-native-yoti-face-capture";

function App(){
    const yotiFaceCaptureRef = useRef(null);
    const windowHeight = useWindowDimensions().height;
    const windowWidth = useWindowDimensions().width;

    // You can then control the camera and analysis using the ref

    // Start the camera
    // yotiFaceCaptureRef.current.startCamera()

    // Start the analysis (having started the camera)
    // yotiFaceCaptureRef.current.startAnalysis()

    // Stop the analysis
    // yotiFaceCaptureRef.current.stopAnalysis()

    // Stop the camera
    // yotiFaceCaptureRef.current.stopCamera()

    return (
        <YotiFaceCapture
            imageQuality={IMAGE_QUALITY_MEDIUM}
            ref={YotiFaceCaptureRef}
            requireEyesOpen={false}
            requiredStableFrames={3}
            requireValidAngle
            requireBrightEnvironment
            faceCenter={[
                0.5,
                0.5
            ]}
            onFaceCaptureAnalyzedImage={({nativeEvent: analysis}) => {
                // analysis.croppedImage
                // analysis.croppedFaceBoundingBox
                // analysis.faceBoundingBox
                // analysis.originalImage
            }}
            onFaceCaptureImageAnalysisFailed={({nativeEvent: failure}) => {
                // failure.cause
                // failure.originalImage
            }}
            onFaceCaptureStateChanged={({nativeEvent: state}) => {
                // state may either be 'Analyzing', 'CameraReady' or 'CameraStopped'
            }}
            onFaceCaptureStateFailed={({nativeEvent: failure}) => {
                // failure may either be 'CameraInitializationError' or 'MissingPermissions'
            }}
        />
    )
}

Configurable props

• imageQuality
• ref
• requireEyesOpen
• requiredStableFrames
• requireValidAngle
• requireBrightEnvironment
• faceCenter
• onFaceCaptureStateChanged
• onFaceCaptureStateFailed
• onFaceCaptureAnalyzedImage
• onFaceCaptureImageAnalysisFailed

imageQuality

This is the image quality of the cropped image after it has been compressed and converted to JPEG. The optional prop defaults to IMAGE_QUALITY_MEDIUM.

ref

A React ref you will use to control the camera and analysis. The ref exposes methods:

• startCamera() - Start the camera feed.
• startAnalysis()- This can be called straight after startCamera(). There is no need to wait for FaceCaptureStateCameraReady.
• stopAnalysis() - Stop the analysis, whenever required.
• stopCamera() - Stop camera feed, whenever required.

requireEyesOpen

Sets the requirement for eyes to be open. When this requirement is not met, an FaceCaptureAnalysisErrorEyesNotOpen error is returned.

• true (default) - require eyes to be open for a face to be considered valid
• false - accepts faces with and without eyes open

requiredStableFrames

Setting this integer will instruct the library to require "n" number of frames to be as similar as possible in terms of width, height and x/y position. The purpose of this is to avoid capturing blurry images. When this requirement is not met, error FaceCaptureAnalysisErrorFaceNotStable is returned. The optional prop defaults to 3.

requireValidAngle

This optional boolean, if true, will require the picture to be taken with a tilt angle no bigger than 30 degrees. When this requirement is not met, error FaceCaptureAnalysisErrorFaceNotStraight is returned.

• true (default) - require face to be straight
• false - allow face to not be straight

requireBrightEnvironment

This optional boolean, if true, will require the picture to be taken in a bright environment. When this requirement is not met, error FaceCaptureAnalysisErrorEnvironmentTooDark is returned.

• true (default) - require bright environment, picture is not taken til the luminosity is good enough
• false - allow the picture to be taken regardless of luminosity

faceCenter

The face center is a Point representing the expected position of the center of the captured face. If the actual face center is not near this point it will not be considered a valid face. This parameter is a percentage value (x, y). E.g.: (0,0) - represents a top left point; (0.5, 0.5) - represents center of the screen; (1,1) - represents a point in the bottom right of the screen;

onFaceCaptureStateChanged

A function to be invoked when the state of Face Capture changes. A string value will be returned, which will be one of:

• FaceCaptureStateCameraReady - The Face Capture has connected to the camera and the preview is available, but no analyzing is happening.
• FaceCaptureStateCameraStopped - The camera has stopped and no analyzing is happening.
• FaceCaptureStateAnalyzing - The camera is ready and the Face Capture is analyzing frames to detect faces.

onFaceCaptureStateFailed

A function to be invoked when the state of Face Capture changes to an error state.

• FaceCaptureStateErrorCameraInitializingError - There was an error initialzing the camera.
• FaceCaptureStateErrorCameraNotAccessible - The Face Capture does not have sufficient permissions to caccess the camera.
• FaceCaptureStateErrorInvalidState - The Face Capture is in an invalid state.

onFaceCaptureAnalyzedImage

A callback function to handle successful face detection. A single parameter will be supplied to the callback, being an object with properties:

• originalImage - This will be a base64 encoded 1280x720 YUV image.
• croppedImage - A compressed, base64 encoded JPEG image based on the configured image quality.
• croppedFaceBoundingBox - The bounding box of the face inside the cropped image.
• faceBoundingBox - The bounding box of the face inside the original image

onFaceCaptureImageAnalysisFailed

A callback function to handle when face detection fails for one of several reasons. A single string value parameter will be supplied to the callback. The value will be one of:

• FaceCaptureAnalysisErrorFaceTooBig
• FaceCaptureAnalysisErrorEyesNotOpen (depending on configuration)
• FaceCaptureAnalysisErrorFaceTooSmall
• FaceCaptureAnalysisErrorFaceNotStable (depending on configuration)
• FaceCaptureAnalysisErrorNoFaceDetected
• FaceCaptureAnalysisErrorFaceNotCentered
• FaceCaptureAnalysisErrorFaceNotStraight (depending on configuration)
• FaceCaptureAnalysisErrorFaceAnalysisFailed
• FaceCaptureAnalysisErrorMultipleFaces
• FaceCaptureAnalysisErrorEnvironmentTooDark (depending on configuration)

Troubleshooting

iOS

Linker errors pertaining to Swift libraries such as swiftFoundation can be resolved with one or more of the solutions mentioned in this oft-quoted StackOverflow discussion, depending on your React Native version and project setup.

Android

Android linking is performed in 3 steps:

android/settings.gradle

Add the following to your settings.gradle file as a new entry before the last line which has include ':app':

+   include ':react-native-yoti-face-capture'
+   project(':react-native-yoti-face-capture').projectDir = new
+   File(rootProject.projectDir, '../node_modules/react-native-yoti-face-capture/src/android')

    include ':app'

android/app/build.gradle

Find the dependencies block in your build.gradle file and add implementation project(':react-native-yoti-face-capture'):

dependencies {
   ...
+   implementation project(':react-native-yoti-face-capture')
}

android/app/src/main/java/..../MainApplication.java

Add an import for the package:

import android.app.Application;
import com.facebook.react.ReactApplication;
+ import com.yoti.reactnative.facecapture.YotiFaceCapturePackage;

Find the getPackages function and add new YotiFaceCapturePackage() to the list of packages.

@Override
protected List<ReactPackage> getPackages() {
    return Arrays.<ReactPackage>asList(
        new MainReactPackage(),
+       new YotiFaceCapturePackage(),
        ...

License

MIT

Support

If you have any other questions please do not hesitate to contact clientsupport@yoti.com. Once we have answered your question we may contact you again to discuss Yoti products and services. If you'd prefer us not to do this, please let us know when you e-mail.