DocumentDetector

The @caf.io/react-native-document-detector library is responsible for capturing identity documents, such as the ID (Brazilian General Registry - RG), Drivers License (CNH), National Foreigner Registry

Requirements

The libraries are compatible only with React Native versions that are 0.66.5 or later.

Android

Settings	Minimum version
minSdkVersion	21
compileSdkVersion	34
Java version	8

iOS

Settings	Minimum version
Target	12
Xcode	14.3.1
Swift	5.5

Installation

yarn add @caf.io/react-native-document-detector
# or 
npm install @caf.io/react-native-document-detector

Android

Inside the android folder in app/build.gradle add the following code:

android {
  ...
  buildFeatures {
    dataBinding = true
  }
}

iOS

In the Podfile in the iOS folder, add this following sources:

source 'https://github.com/combateafraude/iOS.git'
source 'https://cdn.cocoapods.org'

After editing your Podfile, save it and install the SDK along with its dependencies by running the following command:

pod install

Usage

import React from 'react';
import { View, Button, StyleSheet } from 'react-native';
import {
  startDocumentDetector,
  useDocumentDetector,
  DocumentDetectorOptions,
  Stage,
  Document,
} from '@caf.io/react-native-document-detector';

export default function App() {
  const mobileToken: string = "";
  const personId: string = "";

  const options: DocumentDetectorOptions = {
    personId,
    cafStage: Stage.PROD, // optional
    documentSteps: [Document.RG_FRONT, Document.RG_BACK], // required
  }

  const { 
    result, 
    error, 
    cancelled, 
  } = useDocumentDetector(options);

  return (
    <View style={styles.container}>
      <Button 
        title="Press" 
        onPress={() => startDocumentDetector(mobileToken)} 
      />
    </View>
  );
} 

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

Methods

startDocumentDetector

This method inicialize the document detector.

Params

Param	Type	Required	Description
mobileToken	string	Yes	Usage token associated with your Identity account

Hooks

useDocumentDetector

This hook provides the responses of method startDocumentDetector and make the settings for document detector.

Params

Param	Type	Default	Description
settings	DocumentDetectorSettings	Optional	Settings for the document detector

Responses

DocumentDetectorResponse

Types

DocumentDetectorResult

Name	Type	Description
captures	DocumentDetectorCapture[]	The array with the respective captures of the parameterized documents
trackingId	string	Identifier of this run on our servers. If possible, save this field and send it along to our API. This way we will have more data about how the user behaved during the execution
type	string	The class of the read document stream. This parameter is useful in an integration with our OCR route. The existing types are: ["blank", "cnh", "cnh_new", "generic", "rg", "rg_new", "rne", "rnm", "ctps", "passport, crlv, crlv_new"]

DocumentDetectorCapture

Name	Type	Description
imagePath	string	Where the image is located locally
imageUrl	string	URL of the document on CAF's server. If you want this URL, keep enabled the parameter that checks the image quality
label	string	Label of the respective document within the following possibilities: ["blank", "cnh_back", "cnh_front", "cnh_full", "new_cnh_back", "new_cnh_front", "new_cnh_full", "crlv", "crlv_new", "generic", "rg_back", "rg_front", "rg_full", "rg_new_back", "rg_new_front", "rg_new_full", "rne_back", "rne_front", "rnm_back", "rnm_front", "ctps_back", "ctps_front", "passport"]
quality	number	Quality inferred by the document quality algorithm, when enabled. Varies between 1.0 and 5.0

DocumentDetectorError

Name	Type	Description
statusCode	string	Https code status
message	string	Error message
error	Error	Error enum

DocumentDetectorResponse

Name	Type	Description
result	DocumentDetectorResult or null	Shows when face authenticator returns a successful capture
error	DocumentDetectorError or null	Shows when the face authenticator return some error
cancelled	boolean	Shows when user cancel the face authenticator

DocumentDetectorSettings

Name	Type	Description	Android	iOS	Requerid
documentSteps	Document	Defines the document capture flow	✅	✅	Yes
cafStage	Stage	Change the development environment	✅	✅	No
personId	string	User CPF	✅	✅	No
previewSettings	boolean	Enables/disables and allows the configuration of the visualization of the capture performed, requesting the user's confirmation to proceed.	✅	❌	No
uploadSettings	DocumentDetectorUploadSettings	To enable the document upload functionality it is necessary to use this object	✅	✅	No
messageSettings	DocumentDetectorMessageSettings	To custom messages use this object	✅	✅	No
securitySettings	DocumentDetectorSecuritySettings	The SDK has some blocks that may prevent its execution in certain contexts. To disable them, you can use the methods as shown in the example below	✅	❌	No

DocumentDetectorUploadSettings

Name	Type	Description
enable	boolean	Enables/disables this feature
compress	boolean	Enables/disables file compression before uploading
fileFormats	FileFormat[]	Defines the file format(s) that will be accepted for upload
maxFileSize	number	Sets the maximum KB limit of the file to upload

DocumentDetectorMessageSettings

Name	Type	Description	Android	iOS
waitMessage	string	Message displayed when you start the camera	✅	✅
fitTheDocumentMessage	string	Message telling you to fit the document to the mask	✅	✅
holdItMessage	string	Message displayed at the moment the capture is being performed	✅	❌
verifyingQualityMessage	string	Message displayed when the SDK makes a request to the backend, checking for quality	✅	✅
lowQualityDocumentMessage	string	Message displayed when the capture quality fails	✅	✅
uploadingImageMessage	string	Message displayed when there is no quality check and the capture is being saved on the servers	✅	✅
openDocumentWrongMessage	string	Message displayed when displaying an open document, the message will be displayed together with the error message on the document being used, example: if the user displays an open CNH(Brazilian drive’s license), the standard error message "Essa é uma CNH Aberta" + the defined message will be displayed	✅	❌
unsupportedDocumentMessage	string	Message displayed when a unexpected type of document is displayed for capture	✅	✅
documentNotFoundMessage	string	Message displayed when a document is unknown	✅	❌
popupDocumentSubtitleMessage	string	Message displayed in the subtitle of the pop-up that brings the illustration of the document that is being requested for capture.	✅	✅
positiveButtonMessage	string	Allows for customization of the confirmation button message	✅	❌
sensorLuminosityMessage	string	Message displayed when the brightness threshold is lower than expected	✅	✅
sensorOrientationMessage	string	Message displayed when the orientation threshold is lower than expected	✅	✅
sensorStabilityMessage	string	Message displayed when the orientation threshold is lower than expected	✅	✅
wrongDocumentMessageRGFront	string	Message displayed when the front of the RG(Brazilian ID card) is displayed in a different flow than expected	✅	✅
wrongDocumentMessageRGBack	string	Message displayed when the RG(Brazilian ID card) version is displayed in a different flow than expected	✅	✅
wrongDocumentMessageRGFull	string	Message displayed when the open RG(Brazilian ID card) is displayed in a different stream than expected	✅	✅
wrongDocumentMessageCNHFront	string	Message displayed when the front of the CNH(Brazilian driver's license) is displayed in a different stream than expected	✅	✅
wrongDocumentMessageCNHBack	string	Message displayed when the version of the CNH(Brazilian driver's license) is displayed in a different stream than expected	✅	✅
wrongDocumentMessageCNHFull	string	Message displayed when the open CNH(Brazilian driver's license) is displayed in a different stream than expected	✅	✅
wrongDocumentMessageCRLV	string	Message displayed when the CRLV(Brazilian Vehicle Registration and Licensing Certificate) is displayed in a different stream than expected	✅	✅
wrongDocumentMessageRNEFront	string	Message displayed when the front of the RNE(National Registry of Foreigners) is displayed in a different stream than expected	✅	✅
wrongDocumentMessageRNEBack	string	Message displayed when the back of the RNE(National Registry of Foreigners) is displayed in a different stream than expected	✅	✅

DocumentDetectorSecuritySettings

Name	Type	Description
useEmulator	boolean	Enables the use of emulator
useRoot	boolean	Enables the use of rooted devices
useDevelopmentMode	boolean	Enable developer mode on the physical device
useAdb	boolean	Enable the Android Debug Bridge (ADB)
useDebug	boolean	Enable debug mode for Android

Enums

Document

Enum	Description
RG_FRONT	Front of the RG, part where the photo is
RG_BACK	Back of the RG, where the data is
RG_FULL	RG open, showing both the front and back
CNH_FRONT	Front of the CNH, part where the photo is
CNH_BACK	Back of the CNH, part where the signature is
CNH_FULL	CNH open, showing both the front and back
CRLV	CRLV
RNE_FRONT	Front of RNE and RNM, where are the data
RNE_BACK	Back of RNE and RNM, where is the photo
PASSPORT	Passport, one side only, showing all data
CTPS_FRONT	Front of CTPS, where the photo is located
CTPS_BACK	Back of the CTPS, where it contains the data
OTHERS	Other identification documents in general, such as RNE, Military Identity, OAB and CRLV
ANY	Allows the sending of any type of document, all those mentioned above, including any other document, as no typifications are made

FileFormat

Enum	Description	Android	iOS
PNG	image/png	✅	✅
JPG	image/jpg	✅	❌
JPEG	image/jpeg	✅	✅
PDF	image/pdf	✅	✅
HEIF	image/heif	✅	❌

Stage

Enum	Description
BETA	Beta environment
PROD	Production environment

Error

Enum	Description
ServerReason	A server-side error/token invalidation occurred. The associated string (if available) will contain further information about the error
NetworkReason	An error occurred with the video streaming process. The associated string (if available) will contain further information about the error
InvalidTokenReason	The token entered is not valid for the corresponding product
PermissionReason	You are missing some mandatory permission to run the SDK
SecurityReason	When the SDK cannot be started due to a security reason
StorageReason	There is no space on the user device's internal storage
LibraryReason	When an SDK internal library cannot be started
UnexpectedReason	An unxpected error has occurred