@biopassid/fingerprint-sdk-react-native

BioPass ID Fingerprint SDK React Native

Quick Start Guide • Prerequisites • Installation • How to use • LicenseKey • Getting capture status and finger position • Configs • Something else • Changelog • Support

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:

Attention: To use Fingerprint you will need a physical device, Fingerprint does not work on emulators.

	Android	iOS
Support	SDK 24+	iOS 15+

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

2. Installation

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

Android

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

minSdkVersion 24

iOS

Requires iOS 15.0 or higher.

Add to the ios/Info.plist:

• the key Privacy - Camera Usage Description and a usage description.

If editing Info.plist as text, add:

<key>NSCameraUsageDescription</key>
<string>Your camera 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

Privacy manifest file

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>NSPrivacyCollectedDataTypes</key>
	<array>
		<dict>
			<key>NSPrivacyCollectedDataType</key>
			<string>NSPrivacyCollectedDataTypeOtherUserContent</string>
			<key>NSPrivacyCollectedDataTypeLinked</key>
			<false/>
			<key>NSPrivacyCollectedDataTypeTracking</key>
			<false/>
			<key>NSPrivacyCollectedDataTypePurposes</key>
			<array>
				<string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
			</array>
		</dict>
		<dict>
			<key>NSPrivacyCollectedDataType</key>
			<string>NSPrivacyCollectedDataTypeDeviceID</string>
			<key>NSPrivacyCollectedDataTypeLinked</key>
			<false/>
			<key>NSPrivacyCollectedDataTypeTracking</key>
			<false/>
			<key>NSPrivacyCollectedDataTypePurposes</key>
			<array>
				<string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
			</array>
		</dict>
	</array>
	<key>NSPrivacyTracking</key>
	<false/>
	<key>NSPrivacyAccessedAPITypes</key>
	<array>
		<dict>
			<key>NSPrivacyAccessedAPITypeReasons</key>
			<array>
				<string>CA92.1</string>
			</array>
			<key>NSPrivacyAccessedAPIType</key>
			<string>NSPrivacyAccessedAPICategoryUserDefaults</string>
		</dict>
	</array>
</dict>
</plist>

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

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

import React from "react";
import {StyleSheet, View, Button} from "react-native";
import {
  FingerprintCaptureType,
  FingerprintOutputType,
  useFingerprint,
  FingerprintCaptureState,
  FingerprintRect,
  FingerprintConfig,
} from "@biopassid/fingerprint-sdk-react-native";

export default function App() {
  const { takeFingerprint } = useFingerprint();

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

  async function handleButton() {
    await takeFingerprint({
      config,
      onFingerCapture: (images: string[], error: string | null) => {
        if (error) {
          console.log("onFingerCaptured:", error);
        } else {
          console.log("onFingerCaptured:", images[0]?.substring(0, 20));
        }
      },
      onStatusChanged: (state: FingerprintCaptureState) => {
        console.log("onStatusChanged:", state);
      },
      onFingerDetected: (fingerRects: FingerprintRect[]) => {
        console.log("onFingerDetected:", fingerRects);
      },
    });
  }

  return (
    <View style={styles.container}>
      <Button onPress={handleButton} title="Capture Fingers" />
    </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 Fingerprint Capture you need a license key. To set the license key needed is simple as setting another attribute. Simply doing:

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

5. Getting capture status and finger position

You can get the capture status and finger position by passing callback functions when calling takeFingeprint. You can write you own listener following this example:

await takeFingerprint({
  config: { licenseKey: "your-license-key" },
  onFingerCapture: (images: string[], error: string | null) => {
    if (error) {
      console.log("onFingerCaptured:", error);
    } else {
      console.log("onFingerCaptured:", images[0]?.substring(0, 20));
    }
  },
  onStatusChanged: (state: FingerprintCaptureState) => {
    console.log("onStatusChanged:", state);
  },
  onFingerDetected: (fingerRects: FingerprintRect[]) => {
    console.log("onFingerDetected:", fingerRects);
  },
});

FingerprintCaptureState (enum)

Name
FingerprintCaptureState.NO_DETECTION
FingerprintCaptureState.MISSING_FINGERS
FingerprintCaptureState.TOO_CLOSE
FingerprintCaptureState.TOO_FAR
FingerprintCaptureState.OK
FingerprintCaptureState.STOPPED
FingerprintCaptureState.PROCESSING
FingerprintCaptureState.MODEL_NOT_FOUND

FingerprintRect

Name	Type
left	number
top	number
right	number
bottom	number

Configs

FingerprintConfig

Name	Type
licenseKey	string
numberFingersToCapture	number
fontFamily	string
overlayColor	string
timeToCapture	number
captureType	FingerprintCaptureType
outputType	FingerprintOutputType
captureCountdown	FingerprintCaptureCountdownOptions
backButton	FingerprintButtonOptions
helpText	FingerprintHelpTextOptions
fingerEllipse	FingerprintFingerEllipseOptions
distanceIndicator	FingerprintDistanceIndicatorOptions

Default configs:

const defaultConfig: FingerprintConfig = {
  licenseKey: "",
  numberFingersToCapture: 4,
  fontFamily: "fingerprintsdk_opensans_regular",
  overlayColor: "#80000000",
  timeToCapture: 5,
  captureType: FingerprintCaptureType.LEFT_HAND_FINGERS,
  outputType: FingerprintOutputType.CAPTURE_AND_SEGMENTATION,
  captureCountdown: {
    enabled: true,
    backgroundColor: '#50888888',
    progressColor: '#D6A262',
    textColor: '#FFFFFF',
  },
  backButton: {
    enabled: true,
    backgroundColor: "#00000000",
    buttonPadding: 0,
    buttonSize: { width: 56, height: 56 },
    iconOptions: {
      enabled: true,
      iconFile: "fingerprintsdk_ic_close",
      iconColor: "#FFFFFF",
      iconSize: { width: 32, height: 32 },
    },
    labelOptions: {
      enabled: false,
      content: "Voltar",
      textColor: "#FFFFFF",
      textSize: 14,
    },
  },
  helpText: {
    enabled: true,
    messages: {
      leftHandMessage:
        "Encaixe a mão esquerda (sem o polegar)\naté o marcador ficar centralizado.",
      rightHandMessage:
        "Encaixe a mão direita (sem o polegar)\naté o marcador ficar centralizado.",
      thumbsMessage: "Encaixe os polegares\naté o marcador ficar centralizado.",
    },
    textColor: "#FFFFFF",
    textSize: 14,
  },
  fingerEllipse: {
    enabled: true,
    ellipseColor: "#80D6A262",
  },
  distanceIndicator: {
    enabled: true,
    selectedBarColor: "#D6A262",
    unselectedBarColor: "#FFFFFF",
    arrowColor: "#D6A262",
    tooCloseText: {
      enabled: true,
      content: "Muito perto",
      textColor: "#FFFFFF",
      textSize: 14,
    },
    tooFarText: {
      enabled: true,
      content: "Muito longe",
      textColor: "#FFFFFF",
      textSize: 14,
    },
  },
};

FingerprintCaptureType (enum)

Name
FingerprintCaptureType.RIGHT_HAND_FINGERS
FingerprintCaptureType.LEFT_HAND_FINGERS
FingerprintCaptureType.THUMBS

FingerprintOutputType (enum)

Name
FingerprintOutputType.ONLY_CAPTURE
FingerprintOutputType.CAPTURE_AND_SEGMENTATION

FingerprintButtonOptions

Name	Type
enabled	boolean
backgroundColor	string
progressColor	string
textColor	string

FingerprintButtonOptions

Name	Type
enabled	boolean
backgroundColor	string
buttonPadding	number
buttonSize	FingerprintSize
iconOptions	FingerprintIconOptions
labelOptions	FingerprintTextOptions

FingerprintIconOptions

Name	Type
enabled	boolean
iconFile	string
iconColor	string
iconSize	FingerprintSize

FingerprintTextOptions

Name	Type
enabled	boolean
content	string
textColor	string
textSize	number

FingerprintHelpTextOptions

Name	Type
enabled	boolean
messages	FingerprintHelpTextMessages
textColor	string
textSize	number

FingerprintHelpTextMessages

Name	Type
leftHandMessage	string
rightHandMessage	string
thumbsMessage	string

FingerprintSize

Name	Type
width	number
height	number

FingerprintFingerEllipseOptions

Name	Type
enabled	boolean
ellipseColor	string

FingerprintDistanceIndicatorOptions

Name	Type
enabled	boolean
selectedBarColor	string
unselectedBarColor	string
arrowColor	string
tooCloseText	FingerprintTextOptions
tooFarText	FingerprintTextOptions

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 FingerprintConfig in your React Native app.

const config: FingerprintConfig = {
  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 FingerprintConfig in your React Native app.

const config: FingerprintConfig = {
  licenseKey: "your-license-key",
  // Changing back button icon
  backButton: { iconOptions: { iconFile: "ic_baseline_camera" } },
};

Something else

Do you like the Fingerprint SDK and would you like to know about our other products? We have solutions for face detection and digital signature capture.

• Face SDK
  • Face SDK Flutter
  • Face SDK React Native
  • Face SDK JavaScript
• Fingerprint SDK
  • Fingerprint SDK Flutter
  • Fingerprint SDK React Native
• Signature SDK
  • Signature SDK Flutter
  • Signature SDK React Native

Changelog

2.1.1

• Documentation update;
• Dlib has been removed and wrapped in an external lib to avoid conflicts with other BioPasss ID SDKs on Android.

2.1.0

• Documentation update;
• Upgrade minSdkVersion to 24 on Android;
• Improvement in the fluidity of the distance indicator on Android;
• Added continuous autofocus on Android;
• Added new time to capture functionality;
• Added countdown view.

2.0.2

• Documentation update;
• Upgrade to React Native 0.74;
• Upgrade minSdkVersion to 23 on Android;
• Added privacy manifest file on iOS.

2.0.1

• Documentation update;
• Bug fixes.

2.0.0

• Documentation update;
• FingerprintConfig refactoring:
  • Removed showFingerEllipseView and fingerColor, they are now in a new configuration class called FingerprintFingerEllipseOptions;
  • Removed showDistanceIndicatorView, distanceIndicatorLineColor, distanceIndicatorHighlightColor, tooCloseText and tooFarText, now they are in a new configuration class called FingerprintDistanceIndicatorOptions.

1.0.2

• Documentation update;
• Focus improvement for Android.

1.0.1

• Documentation update;
• Fixed back button padding for Android;
• Fixed bug that caused a crash when pressing the back button for Android.

1.0.0

• Documentation update;
• Refactoring in onFingerCapture:
  • Now, in addition to the image list, an error message is also returned.
• Removed automatic restart in case of fingerprint extraction failure:
  • Now, if the fingerprint extraction fails, a String will be returned with an error message.

Before

const images = await takeFingerprint({
  config: { licenseKey: "your-license-key" },
});
console.log("onFingerCaptured:", images[0]?.substring(0, 20));

Now

await takeFingerprint({
  config: { licenseKey: "your-license-key" },
  onFingerCapture: (images: string[], error: string | null) => {
    if (error) {
      console.log("onFingerCaptured:", error);
    } else {
      console.log("onFingerCaptured:", images[0]?.substring(0, 20));
    }
  },
});

0.1.4

• Documentation update;
• Bug fixes.

0.1.3

• Documentation update;
• Bug fixes.

0.1.2

• Documentation update;
• Fix in focus and exposure mode for Android.

0.1.1

• Documentation update;
• Correction in the resolution of the returned images for iOS;
• Improvement in focus and exposure mode for Android.

0.1.0

• Documentation update;
• Removal of FingerprintCaptureListener;
• Customizable UI.

0.0.10

• Documentation update;
• Focus adjustments for Android.

0.0.9

• Documentation update;
• License functionality fix for iOS.

0.0.8

• Documentation update.

0.0.7

• Documentation update;
• Improved license functionality for iOS.

0.0.6

• Finger capture;
• Fingers segmentation;
• Parameterizable distance, status and fingers indicators.
• Documentation update;
• dlib bug fix;
• New licensing feature;
• Finger indicator fix.