@biopassid/face-sdk-react-native

BioPass ID Face SDK React Native

Table of Contents

• Quick Start Guide
  • Prerequisites
  • Installation
  • How to use
  • Callback
  • License
• FaceConfig
• FaceEvent
• Changelog
• License

Quick Start Guide

First, you will need a license key to use the SDK. You can acquire a license key when subscribing to a BioPass ID plan.

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

1. Prerequisites:

	Android
Support	SDK 21+

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

2. Installation

npm install @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

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

compileSdkVersion 31

3. How to use

Basic Example

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

import React from "react";
import { StyleSheet, View, Button } from "react-native";
import {
  FaceConfigPreset,
  FaceConfigType,
  FaceEvent,
  buildCameraView,
  FaceCameraLensDirection,
} from "@biopassid/face-sdk-react-native";

export function App() {
  const config = FaceConfigPreset.getConfig(
    FaceConfigType.FACE_CAPTURE
  )
    .setLicenseKey("your-license-key")
    .setDefaultCameraPosition(FaceCameraLensDirection.FRONT)
    .setShowFlipCameraButton(true)
    .setStringsScreenTitle("Capturando Face")
    .setStylesOverlayColor("#CC000000");

  function callback(event: FaceEvent) {
    // handle Face return
    console.log(event.photo);
  }

  function handleButton() {
    buildCameraView(config, callback);
  };

  return (
    <View style={styles.container}>
      <Button onPress={handleButton} 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 Enroll from the Multibiometrics package.

Here, you will need an API key to be able to make requests to the BioPass ID API.

import React from 'react';
import {StyleSheet, View, Button} from 'react-native';
import {
  FaceConfigPreset,
  FaceConfigType,
  FaceEvent,
  buildCameraView,
} from '@biopassid/face-sdk-react-native';
import {Base64} from './utils/Base64';

export default function App() {
  // Instantiate Face config by passing your license key
  const config = FaceConfigPreset.getConfig(
    FaceConfigType.FACE_CAPTURE,
  ).setLicenseKey('your-license-key');

  // Handle Face callback
  async function callback(event: FaceEvent) {
    // Encode image to base64 string
    const imageBase64 = Base64.arrayBufferToBase64(event.photo);

    // 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': imageBase64}],
      },
    });

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

  // Build Face camera view
  function handleButton() {
    buildCameraView(config, callback);
  }

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

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

Base64 util

const chars =
  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=';

export const Base64 = {
  btoa: (input: string = '') => {
    let str = input;
    let output = '';

    for (
      let block = 0, charCode, i = 0, map = chars;
      str.charAt(i | 0) || ((map = '='), i % 1);
      output += map.charAt(63 & (block >> (8 - (i % 1) * 8)))
    ) {
      charCode = str.charCodeAt((i += 3 / 4));

      if (charCode > 0xff) {
        throw new Error(
          "'btoa' failed: The string to be encoded contains characters outside of the Latin1 range.",
        );
      }

      block = (block << 8) | charCode;
    }

    return output;
  },

  arrayBufferToBase64: (buffer: ArrayBuffer) => {
    var binary = '';
    var bytes = new Uint8Array(buffer);
    bytes.forEach((item: number) => {
      binary += String.fromCharCode(item);
    });
    return Base64.btoa(binary);
  },
};

4. Callback

Setting the Callback

You can pass a function callback to receive the captured image. You can write you own callback following this example:

function callback(event: FaceEvent) {
  console.log('photo: ', event.photo);
  doSomething(event);
}

5. License

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

const config = FaceConfigPreset.getConfig(FaceConfigType.FACE_CAPTURE)
  .setLicenseKey('your-license-key');

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:

FaceCaptureConfig

Variable name	Type	Default value
licenseKey	string	""
cameraPreset	FaceCameraPreset	FaceCameraPreset.FACE_CAPTURE
defaultCameraPosition	FaceCameraLensDirection	FaceCameraLensDirection.FRONT
outputFormat	FaceOutputFormat	FaceOutputFormat.JPEG
captureButtonType	FaceCaptureButtonType	FaceCaptureButtonType.DEFAULT
showFlashButton	boolean	false
showFlipCameraButton	boolean	true
flashEnabledByDefault	boolean	false
showHelpText	boolean	true
showScreenTitle	boolean	true
autoCapture	bool	true
strings	FaceStrings
styles	FaceStyles

ContinuousCaptureConfig

Variable name	Type	Default value
licenseKey	string	""
cameraPreset	FaceCameraPreset	FaceCameraPreset.FACE_CAPTURE
defaultCameraPosition	FaceCameraLensDirection	FaceCameraLensDirection.FRONT
outputFormat	FaceOutputFormat	FaceOutputFormat.JPEG
captureButtonType	FaceCaptureButtonType	FaceCaptureButtonType.DEFAULT
showFlashButton	boolean	false
showFlipCameraButton	boolean	false
flashEnabledByDefault	boolean	false
showHelpText	boolean	true
showScreenTitle	boolean	true
autoCapture	bool	true
strings	FaceStrings
styles	FaceStyles

FaceStrings

Variable name	Type	Default value
screenTitle	string	"Capturando Face"
helpText	string	"Encaixe seu rosto no formato acima e aguarde o sinal verde"
loading	string	"Processando..."
customCaptureButtonText (Android only)	string	"Capture Face"
noFaceDetectedMessage (Android only)	string	"Nenhuma face detectada"
multipleFacesDetectedMessage (Android only)	string	"Múltiplas faces detectadas"
detectedFaceIsCenteredMessage (Android only)	string	"Mantenha o celular parado"
detectedFaceIsCloseMessage (Android only)	string	"Afaste o rosto da câmera"
detectedFaceIsDistantMessage (Android only)	string	"Aproxime o rosto da câmera"
detectedFaceIsOnTheLeftMessage (Android only)	string	"Mova o celular para a direita"
detectedFaceIsOnTheRightMessage (Android only)	string	"Mova o celular para a esquerda"
detectedFaceIsTooUpMessage (Android only)	string	"Mova o celular para baixo"
detectedFaceIsTooDownMessage (Android only)	string	"Mova o celular para cima"

FaceStyles

Variable name	Type	Default value
faceColor	string	"#FFFFFF"
faceEnabledColor (Android only)	string	"#16AC81"
faceDisabledColor (Android only)	string	"#E25353"
overlayColor	string	"#CC000000"
backButtonIcon (Android only)	string	null
backButtonColor (Android only)	string	"#FFFFFF"
backButtonSize (Android only)	FaceSize	FaceSize(24, 24)
flashButtonIcon (Android only)	string	null
flashButtonSize (Android only)	FaceSize	FaceSize(24, 24)
flashButtonEnabledColor	string	"#FFCC01"
flashButtonDisabledColor (Android only)	string	"#FFFFFF"
flipCameraButtonIcon (Android only)	string	null
flipCameraButtonColor (Android only)	string	"#FFFFFF"
flipCameraButtonSize (Android only)	FaceSize	FaceSize(65, 43)
textColor (Android only)	string	"#FFFFFF"
textSize (Android only)	number	20
customFont (Android only)	string	null
captureButtonIcon (Android only)	string	null
captureButtonColor	string	"#D9D9D9"
captureButtonSize (Android only)	FaceSize	FaceSize(76, 76)
customCaptureButtonBackgroundColor (Android only)	string	"#D6A262"
customCaptureButtonSize (Android only)	FaceSize	FaceSize(300, 45)
customCaptureButtonTextColor (Android only)	string	"#FFFFFF"
customCaptureButtonTextSize (Android only)	number	20

Changing Font Family

You can use the default font family or set a font you prefer. 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 names must be only: lowercase a-z, 0-9, or underscore. The structure should be some thing like below.

Then, just set the font passing the name of the font file.

const config = FaceConfigPreset.getConfig(FaceConfigType.FACE_CAPTURE)
  .setStylesFontFamily("roboto_mono_bold_italic");

Changing Icon

You can use the default icon or set a icon you prefer. To set a icon, download the icon which ever you want and paste it inside drawable folder in your android/app/src/main/res. The structure should be some thing like below.

Then, just set the font passing the name of the icon file.

const config = FaceConfigPreset.getConfig(FaceConfigType.FACE_CAPTURE)
  // changing back button icon
  .setStylesBackButtonIcon("ic_baseline_camera")
  // changing flash button icon
  .setStylesFlashButtonIcon("ic_baseline_camera")
  // changing flip camera button icon
  .setStylesFlipCameraButtonIcon("ic_baseline_camera")
  // changing capture button icon
  .setStylesCaptureButtonIcon("ic_baseline_camera");

FaceSize

Variable name	Type
width	number
height	number

FaceCameraPreset (enum)

Preset Type	Resolution
FaceCameraPreset.FACE_CAPTURE	640x480
FaceCameraPreset.CONTINUOUS_CAPTURE	640x480

FaceCameraLensDirection (enum)

Name
FaceCameraLensDirection.FRONT
FaceCameraLensDirection.BACK

FaceCaptureFormat (enum)

Name
FaceCaptureFormat.JPEG
FaceCaptureFormat.PNG

FaceCaptureButtonType (enum)

Name
FaceCaptureButtonType.CUSTOM
FaceCaptureButtonType.ICON

Using Custom Capture Button

const config = FaceConfigPreset.getConfig(FaceConfigType.FACE_CAPTURE)
  .setCaptureButtonType(FaceCaptureButtonType.CUSTOM)
  .setStylesCustomButtonBackgroundColor("#FFFF00")
  .setStylesCustomButtonTextColor("#FF00FF")
  .setStringsCustomButtonText("Capture");

Using Icon Capture Button

const config = FaceConfigPreset.getConfig(FaceConfigType.FACE_CAPTURE)
    .setCaptureButtonType(FaceCaptureButtonType.ICON)
    .setStylesCaptureButtonIcon("ic_baseline_camera")
    .setStylesCaptureButtonColor("#FF0000")
    .setStylesCaptureButtonSize({width: 76, height: 76});

How to instantiate and functionalities

To instantiate it's easy as to do one function call (as we have seen previously on the example). You only need to specify which type of config you want using a ENUM FaceConfigType. Every type however can have different features implemented, here are the supported types:

Config Type	Enum	feature
Face Capture	FaceConfigType.FACE_CAPTURE	Capture still image and detects face
Continuous Capture	FaceConfigType.CONTINUOUS_CAPTURE	Capture every frame per second

FaceEvent

On your Face callback function, you receive a FaceEvent.

FaceEvent

Name	Type
photo	Uint8Array

Changelog

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

License

This project is under the MIT license. See the LICENSE for more information.