@biopassid/face-sdk-react-native

BioPass ID Face SDK React Native

Key Features • Customizations • Quick Start Guide • Prerequisites • Installation • How to use • LicenseKey • FaceConfig • Changelog • Support

Key features

• Face Detection
  • We ensure that there will be only one face in the capture.
• Face Positioning
  • Ensure face position in your capture for better enroll and match.
• Auto Capture
  • When a face is detected the capture will be performed in how many seconds you configure.
• Resolution Control
  • Configure the image size thinking about the tradeoff between image quality and API's response time.
• Aspect Ratio Control
• Fully customizable interface

Customizations

Increase the security of your applications without harming your user experience.

All customization available:

• Title Text
• Help Text
• Loading Text
• Font Family
• Face Frame
• Overlay
• Default Camera
• Capture button

Enable or disable components:

• Tittle text
• Help Text
• Capture button
• Button icons
• Flip Camera button
• Flash button

Change all colors:

• Overlay color and opacity
• Capture button color
• Capture button text color
• Flip Camera color
• Flash Button color
• Text colors

Quick Start Guide

First, you will need a license key to use the SDK. To get your license key contact us through our website BioPass ID.

Check out our official documentation for more in depth information on BioPass ID.

1. Prerequisites:

	Android	iOS
Support	SDK 21+	iOS 14+

- A device with a camera
- License key
- Internet connection is required to verify the license

2. Installation

npm install @biopassid/face-sdk-react-native

If you are using Yarn:

yarn add @biopassid/face-sdk-react-native

Android

Change the minimum Android sdk version to 21 (or higher) in your android/app/build.gradle file.

minSdkVersion 21

iOS

Requires iOS 14.0 or higher.

Add two rows to the ios/Info.plist:

• one with the key Privacy - Camera Usage Description and a usage description.
• and one with the key Privacy - Photo Library Usage Description and a usage description.

If editing Info.plist as text, add:

<key>NSCameraUsageDescription</key>
<string>Your camera usage description</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Your library usage description</string>

Then go into your project's ios folder and run pod install.

# Go into ios folder
$ cd ios

# Install dependencies
$ pod install

Expo

• ✅ You can use this library with Development Builds. No config plugin is required.
• ❌ This library can't be used in the "Expo Go" app because it requires custom native code.

3. How to use

Basic Example

To call Face in your React Native project is as easy as follow:

import React from "react";
import { StyleSheet, View, Button } from "react-native";
import { useFace } from "@biopassid/face-sdk-react-native";

export default function App() {
  const { takeFace } = useFace();

  async function onPress() {
    await takeFace({
      config: { licenseKey: "your-license-key" },
      onFaceCapture: (image: string) => {
        console.log("Image: ", image.substring(0, 20));
      },
    });
  }

  return (
    <View style={styles.container}>
      <Button onPress={onPress} title="Capture Face" />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: "center",
    justifyContent: "center",
    backgroundColor: '#FFFFFF',
  },
});

Example using Fetch API to call the BioPass ID API

For this example we used the Enroll from the Multibiometrics plan.

Here, you will need an API key to be able to make requests to the BioPass ID API. To get your API key contact us through our website BioPass ID.

import React from "react";
import { StyleSheet, View, Button } from "react-native";
import { useFace } from "@biopassid/face-sdk-react-native";

export default function App() {
  const { takeFace } = useFace();

  function onFaceCapture(image: string) {
     // Create headers passing your api key
    const headers = {
      "Content-Type": "application/json",
      "Ocp-Apim-Subscription-Key": "your-api-key",
    };

    // Create json body
    const body = JSON.stringify({
      Person: {
        CustomID: "your-customID",
        Face: [{"Face-1": image}],
      },
    });

    // Execute request to BioPass ID API
    const response = await fetch(
      "https://api.biopassid.com/multibiometrics/enroll",
      {
        method: "POST",
        headers,
        body,
      },
    );
    const data = await response.json();

    // Handle API response
    console.log("Response status: ", response.status);
    console.log("Response body: ", data);
  }

  async function onPress() {
    await takeFace({
      config: { licenseKey: "your-license-key" },
      onFaceCapture,
    });
  }

  return (
    <View style={styles.container}>
      <Button onPress={onPress} title="Capture Face" />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: "center",
    justifyContent: "center",
    backgroundColor: "#FFFFFF",
  },
});

4. LicenseKey

First, you will need a license key to use the SDK. To get your license key contact us through our website BioPass ID.

To use Face you need a license key. To set the license key needed is simple as setting another attribute. Simply doing:

const config: FaceConfig = {
  licenseKey: "your-license-key",
};

5. Getting face capture

You can pass a function callback to receive the captured image. Images are returned in Base64 string format. You can write you own callback following this example:

function onFaceCapture(image: string) {
  console.log("Image: ", image.substring(0, 20));
}

async function onPress() {
  await takeFace({
    config: { licenseKey: "your-license-key" },
    onFaceCapture,
  });
}

6. Continuous capture

You can use continuous capture to capture multiple frames at once. In addition, you can set a maximum number of frames to be captured using maxNumberFrames. As well as the capture time with timeToCapture. Use continuous capture is as simple as setting another attribute. Simply by doing:

const config: FaceConfig = {
  licenseKey: "your-license-key",
  continuousCapture: {
    enabled: true,
    timeToCapture: 1000, // capture every frame per second, time in millisecond
    maxNumberFrames: 40,
  },
};

7. Face detection

With Face SDK you can use face detection to do face detection and automatic capture. Below you can see the options that are available for this functionality.

Auto capture

For automatic capture to work, autoCapture needs to be enabled. By default, autoCapture is already enabled. If autoCapture is disabled, automatic capture will be disabled and the responsibility for capturing will be the user's responsibility through a button. For continuous capture, autoCapture will be ignored and automatic capture will always occur. To set autoCapture is simple as setting another attribute. Simply doing:

const config: FaceConfig = {
  licenseKey: "your-license-key",
  faceDetection: { enabled: true, autoCapture: true },
};

Time to capture

TimeToCapture is a time in milliseconds that is triggered before the capture. To use timeToCapture, autoCapture needs to be on and a time in milliseconds needs to be passed to timeToCapture. By default, timeToCapture value is 3000ms. If timeToCapture is equal to zero, the capture will be instantaneous. To set timeToCapture is simple as setting another attribute. Simply doing:

const config: FaceConfig = {
  licenseKey: "your-license-key",
  faceDetection: {
    enabled: true,
    autoCapture: true,
    timeToCapture: 3000, // time in millisecond
  },
};

Max face detection time

You can use maxFaceDetectionTime to set a maximum time in milliseconds that face detection will be active. If after this time the SDK is unable to identify a face, face detection will be disabled and a capture button will be displayed, thus passing the capture responsibility to the user. The time will only start counting after a first detection attempt. By default, the value of maxFaceDetectionTime is 40000 ms. This functionality only affects single capture mode. Setting maxFaceDetectionTime is as simple as setting another attribute. Simply by doing:

const config: FaceConfig = {
  licenseKey: 'your-license-key',
  faceDetection: {
    enabled: true,
    maxFaceDetectionTime: 40000, // time in millisecond
  },
};

FaceConfig

You can also use pre-build configurations on your application, so you can automatically start using multiples services and features that better suit your application. You can instantiate each one and use it's default properties, or if you prefer you can change every config available. Here are the types that are supported right now:

FaceConfig

Name	Type
licenseKey	string
resolutionPreset	FaceResolutionPreset
lensDirection	FaceCameraLensDirection
imageFormat	FaceImageFormat
flashEnabled	boolean
fontFamily	string
continuousCapture	FaceContinuousCaptureOptions
faceDetection	FaceDetectionOptions
mask	FaceMaskOptions
titleText	FaceTextOptions
loadingText	FaceTextOptions
helpText	FaceTextOptions
feedbackText	FaceFeedbackTextOptions
backButton	FaceButtonOptions
flashButton	FaceFlashButtonOptions
switchCameraButton	FaceButtonOptions
captureButton	FaceButtonOptions

Default configs:

const defaultConfig: FaceConfig = {
  licenseKey: "",
  resolutionPreset: FaceResolutionPreset.MEDIUM,
  lensDirection: FaceCameraLensDirection.FRONT,
  imageFormat: FaceImageFormat.JPEG,
  flashEnabled: false,
  fontFamily: "facesdk_opensans_bold",
  continuousCapture: {
    enabled: false,
    timeToCapture: 1000,
    maxNumberFrames: 40,
  },
  faceDetection: {
    enabled: true,
    autoCapture: true,
    multipleFacesEnabled: false,
    timeToCapture: 3000,
    maxFaceDetectionTime: 40000,
  },
  mask: {
    enabled: true,
    type: FaceMaskFormat.FACE,
    backgroundColor: "#CC000000",
    frameColor: "#FFFFFF",
    frameEnabledColor: "#16AC81",
    frameErrorColor: "#E25353",
  },
  titleText: {
    enabled: true,
    content: "Capturando Face",
    textColor: "#FFFFFF",
    textSize: 20,
  },
  loadingText: {
    enabled: true,
    content: "Processando...",
    textColor: "#FFFFFF",
    textSize: 14,
  },
  helpText: {
    enabled: true,
    content: "Encaixe seu rosto no formato abaixo",
    textColor: "#FFFFFF",
    textSize: 14,
  },
  feedbackText: {
    enabled: true,
    messages: {
      noFaceDetectedMessage: "Nenhuma face detectada",
      multipleFacesDetectedMessage: "Múltiplas faces detectadas",
      detectedFaceIsCenteredMessage: "Mantenha o celular parado",
      detectedFaceIsTooCloseMessage: "Afaste o rosto da câmera",
      detectedFaceIsTooFarMessage: "Aproxime o rosto da câmera",
      detectedFaceIsOnTheLeftMessage: "Mova o celular para a direita",
      detectedFaceIsOnTheRightMessage: "Mova o celular para a esquerda",
      detectedFaceIsTooUpMessage: "Mova o celular para baixo",
      detectedFaceIsTooDownMessage: "Mova o celular para cima",
      faceDetectionDisabledMessage: "Detecção facial desabilitada",
    },
    textColor: "#FFFFFF",
    textSize: 14,
  },
  backButton: {
    enabled: true,
    backgroundColor: "#00000000",
    buttonPadding: 10,
    buttonSize: { width: 56, height: 56 },
    iconOptions: {
      enabled: true,
      iconFile: "facesdk_ic_close",
      iconColor: "#FFFFFF",
      iconSize: { width: 32, height: 32 },
    },
    labelOptions: {
      enabled: false,
      content: "Voltar",
      textColor: "#FFFFFF",
      textSize: 14,
    },
  },
  flashButton: {
    enabled: false,
    backgroundColor: "#FFFFFF",
    buttonPadding: 10,
    buttonSize: { width: 56, height: 56 },
    flashOnIconOptions: {
      enabled: true,
      iconFile: "facesdk_ic_flash_on",
      iconColor: "#FFCC01",
      iconSize: { width: 32, height: 32 },
    },
    flashOnLabelOptions: {
      enabled: false,
      content: "Flash On",
      textColor: "#323232",
      textSize: 14,
    },
    flashOffIconOptions: {
      enabled: true,
      iconFile: "facesdk_ic_flash_off",
      iconColor: "#323232",
      iconSize: { width: 32, height: 32 },
    },
    flashOffLabelOptions: {
      enabled: false,
      content: "Flash Off",
      textColor: "#323232",
      textSize: 14,
    },
  },
  switchCameraButton: {
    enabled: true,
    backgroundColor: "#FFFFFF",
    buttonPadding: 10,
    buttonSize: { width: 56, height: 56 },
    iconOptions: {
      enabled: true,
      iconFile: "facesdk_ic_switch_camera",
      iconColor: "#323232",
      iconSize: { width: 32, height: 32 },
    },
    labelOptions: {
      enabled: false,
      content: "Trocar Câmera",
      textColor: "#323232",
      textSize: 14,
    },
  },
  captureButton: {
    enabled: true,
    backgroundColor: "#FFFFFF",
    buttonPadding: 10,
    buttonSize: { width: 56, height: 56 },
    iconOptions: {
      enabled: true,
      iconFile: "facesdk_ic_capture",
      iconColor: "#323232",
      iconSize: { width: 32, height: 32 },
    },
    labelOptions: {
      enabled: false,
      content: "Capturar",
      textColor: "#323232",
      textSize: 14,
    },
  },
};

FaceContinuousCaptureOptions

Name	Type
enabled	boolean
timeToCapture	number // time in milliseconds
maxNumberFrames	number

FaceDetectionOptions

Name	Type
enabled	boolean
autoCapture	boolean
multipleFacesEnabled	boolean
timeToCapture	number // time in milliseconds
maxFaceDetectionTime	number // time in milliseconds

FaceMaskOptions

Name	Type
enabled	boolean
type	FaceMaskFormat
backgroundColor	string
frameColor	string
frameEnabledColor	string
frameErrorColor	string

FaceFeedbackTextOptions

Name	Type
enabled	boolean
messages	FaceFeedbackTextMessages
textColor	string
textSize	number

FaceFeedbackTextMessages

Name	Type
noFaceDetectedMessage	string
multipleFacesDetectedMessage	string
detectedFaceIsCenteredMessage	string
detectedFaceIsTooCloseMessage	string
detectedFaceIsTooFarMessage	string
detectedFaceIsOnTheLeftMessage	string
detectedFaceIsOnTheRightMessage	string
detectedFaceIsTooUpMessage	string
detectedFaceIsTooDownMessage	string
faceDetectionDisabledMessage	string

FaceFlashButtonOptions

Name	Type
enabled	boolean
backgroundColor	string
buttonPadding	number
buttonSize	FaceSize
flashOnIconOptions	FaceIconOptions
flashOnLabelOptions	FaceTextOptions
flashOffIconOptions	FaceIconOptions
flashOffLabelOptions	FaceTextOptions

FaceButtonOptions

Name	Type
enabled	boolean
backgroundColor	string
buttonPadding	number
buttonSize	FaceSize
iconOptions	FaceIconOptions
labelOptions	FaceTextOptions

FaceIconOptions

Name	Type
enabled	boolean
iconFile	string
iconColor	string
iconSize	FaceSize

FaceTextOptions

Name	Type
enabled	boolean
content	string
textColor	string
textSize	number

FaceCameraLensDirection (enum)

Name
FaceCameraLensDirection.FRONT
FaceCameraLensDirection.BACK

FaceImageFormat (enum)

Name
FaceImageFormat.JPEG
FaceImageFormat.PNG

FaceMaskFormat (enum)

Name
FaceScreenShape.FACE
FaceScreenShape.SQUARE
FaceScreenShape.ELLIPSIS

FaceResolutionPreset (enum)

Name	Resolution
FaceResolutionPreset.LOW	240p (352x288 on iOS, 320x240 on Android)
FaceResolutionPreset.MEDIUM	480p (640x480 on iOS, 720x480 on Android)
FaceResolutionPreset.HIGH	720p (1280x720)
FaceResolutionPreset.VERYHIGH	1080p (1920x1080)
FaceResolutionPreset.ULTRAHIGH	2160p (3840x2160)
FaceResolutionPreset.MAX	The highest resolution available

How to change font family

on Android side

You can use the default font family or set one of your own. To set a font, create a folder font under res directory in your android/app/src/main/res. Download the font which ever you want and paste it inside font folder. All font file names must be only: lowercase a-z, 0-9, or underscore. The structure should be some thing like below.

on iOS side

To add the font files to your Xcode project:

1. In Xcode, select the Project navigator.
2. Drag your fonts from a Finder window into your project. This copies the fonts to your project.
3. Select the font or folder with the fonts, and verify that the files show their target membership checked for your app’s targets.

Then, add the "Fonts provided by application" key to your app’s Info.plist file. For the key’s value, provide an array of strings containing the relative paths to any added font files.

In the following example, the font file is inside the fonts directory, so you use fonts/roboto_mono_bold_italic.ttf as the string value in the Info.plist file.

on JS side

Finally, just set the font passing the name of the font file when instantiating FaceConfig in your React Native app.

const config: FaceConfig = {
  licenseKey: "your-license-key",
  fontFamily: "roboto_mono_bold_italic",
};

How to change icon

on Android side

You can use the default icons or define one of your own. To set a icon, download the icon which ever you want and paste it inside drawable folder in your android/app/src/main/res. All icon file names must be only: lowercase a-z, 0-9, or underscore. The structure should be some thing like below.

on iOS side

To add icon files to your Xcode project:

1. In the Project navigator, select an asset catalog: a file with a .xcassets file extension.
2. Drag an image from the Finder to the outline view. A new image set appears in the outline view, and the image asset appears in a well in the detail area.

on JS side

Finally, just set the icon passing the name of the icon file when instantiating FaceConfig in your React Native app.

const config: FaceConfig = {
  licenseKey: "your-license-key",
  // Changing back button icon
  backButton: { iconOptions: { iconFile: "ic_baseline_camera" } },
  // Changing switch camera button icon
  switchCameraButton: { iconOptions: { iconFile: "ic_baseline_camera" } },
  // Changing capture button icon
  captureButton: { iconOptions: { iconFile: "ic_baseline_camera" } },
  // Changing flash button icon
  flashButton: {
    flashOnIconOptions: { iconFile: 'ic_baseline_camera' },
    flashOffIconOptions: { iconFile: 'ic_baseline_camera' },
  },
};

Changelog

v2.0.0

• Documentation update;
• Refactoring in FaceConfig;
• Refactoring in UI customization functionality.

v1.2.2

• Documentation update;
• Bug fixes and improvements.

v1.2.1

• Documentation update;
• Bug fix in maxFaceDetectionTime for Android.

v1.2.0

• Documentation update;
• Refactoring on autoCaptureTimeout:
  • Now the autoCaptureTimeout is called timeToCapture.
• New feature maxFaceDetectionTime:
  • It is now possible to set a maximum time that face detection will be active.

v1.1.1

• Documentation update.

v1.1.0

• New feature maxNumberFrames:
  • It is now possible to set a maximum number of frames to be captured during continuous capture.
• Documentation update.

v1.0.1

• Documentation update;
• Fixed a bug that caused the camera preview image to be stretched during continuous capture for Android;
• Improved license functionality for iOS.

v1.0.0

• Documentation update;
• FaceCameraPreset Refactoring;
• FaceEvent refactoring:
  • Now the photo is returned in Base64 string format.
• Fix autoCaptute and autoCaptuteTimeout for iOS;
• Fix CustomFonts feature for iOS.

v0.1.23

• Documentation update;
• New config option autoCaptureTimeout;
• UI customization improvements:
  • Added FaceScreenShape with more face shape options;
  • Added progress animation during face detection.

v0.1.22

• Bug fixes;
• Documentation update.

v0.1.21

• Bug fixes.

v0.1.20

• New licensing feature.

v0.1.19

• Bug fix.

v0.1.18

• Bug fixes;
• Flash mode fixes;
• Face detection improvement;
• New feature automatic capture;
• UI customization improvements;
• New feature face detection;
• Camera preset fix;
• Camera preview fix;
• New icon capture button;
• Fix in requesting permissions;
• Fix in performance of ContinuousCapture;
• Parameterizable screenTitle;
• New option to set text color;
• New custom capture button;
• Class name standardization;
• New option to set the font.

v0.1.13

• Face Capture SDK for Android and iOS.