DocumentDetector

Plugin that calls native SDKs in Android and iOS.

Currently, the supported documents are RG, CNH, RNE and CRLV. If you have any suggestions for other documents, please contact us!

Importing

import {DocumentDetector, DocumentDetectorStep, DocumentType} from 'document-detector-ionic';

Using

let documentDetector = new DocumentDetector();

documentDetector.setMobileToken = '<your mobile token>';

var documentDetectorSteps: Array<DocumentDetectorStep> = [
    new DocumentDetectorStep(DocumentType.RG_FRONT, null, null),
    new DocumentDetectorStep(DocumentType.RG_BACK, null, null)];
    
documentDetector.setDocumentDetectorSteps = documentDetectorSteps;

var response = await documentDetector.start();

if(response.result == "SUCCESS"){
    // Success
}else if(response.result == "FAILURE"){
    // Fail. Check reponse.type and response.message
}else{
    // User closed the screen
}

General customizations

DocumentDetector

.setPeopleId(String peopleId)

CPF of the user who is using the plugin to be used for fraud detection via analytics

.setUseAnalytics(bool useAnalytics)

Enables/disables data collection for maximizing anti-fraud information. Default is true

.setDocumentFlow(List<DocumentDetectorStep> documentSteps)

Flow of documents to be captured in the SDK

.setPopup(bool show)

Change the setting for the inflated popups before each document. The default is true

.setSound(bool enable)

Enables/disables sounds. The default is true

.setNetworkSettings(int requestTimeout)

Changes the default network settings. The default is 60 seconds

.setShowPreview(ShowPreview showPreview)

Preview for checking photo quality

.setAndroidSettings(DocumentDetectorAndroidSettings androidSettings)

Customizations only applied on Android

.setIosSettings(DocumentDetectorIosSettings iosSettings)

Customizations only applied on iOS

DocumentDetectorStep constructor

DocumentType document

Document to be scanned in this respective step

DocumentDetectorStepCustomizationAndroid android

Visual customizations of the respective step applied on Android

DocumentDetectorStepCustomizationIos ios

Visual customizations of the respective step applied on iOS

ShowPreview

If you want to customize the values, create a String in ROOT_PROJECT/android/app/src/main/res/values/strings.xml with the desired name and value and parameterize

bool show

Preview Enable/Disable

String title

Title

String subTitle

Subtitle

String confirmLabel

Confirmation Pushbutton Text

String retryLabel

Re-capture Button Text

Android

DocumentDetectorStepCustomizationAndroid constructor

String stepLabelStringResName

Name of the string resource to be shown in the document name label. For example, if you want to show the String "Test", create a String in ROOT_PROJECT/android/app/src/main/res/values/strings.xml with the name R.string.my_custom_string and value "Test" and parametrize "my_custom_string".

String illustrationDrawableResName

Name of the drawable resource to be shown in the capture intro popup. For example, if you want to show a custom illustration, save it in ROOT_PROJECT/android/app/src/main/res/drawable/my_custom_illustration.png and parameterize "my_custom_illustration".

String audioRawResName

Name of the raw resource to run at the start of the capture. For example, if you want to play a custom audio, save it in ROOT_PROJECT/android/app/src/main/res/raw/my_custom_audio.mp3 and parameterize "my_custom_audio".

DocumentDetectorAndroidSettings constructor

DocumentDetectorCustomizationAndroid customization

Customization of the activity's Android layout

SensorSettingsAndroid sensorSettings

Customization of the capture sensor settings

List<CaptureStage> captureStages

Array of stages for each capture. This parameter is useful if you want to change the way the DocumentDetector runs, such as detection settings, automatic or manual capture, checking photo quality, etc.

bool enableSwitchCameraButton

Permite habilitar ou desabilitar o botão de inversão da câmera. O padrão é True

CaptureStage constructor

int durationMillis

Duration in milliseconds of this respective step before moving on to the next, if any. null to infinity

bool wantSensorCheck

Flag indicating if this stage should/should not undergo sensor validation

QualitySettings qualitySettings

Document Quality Check Settings. The only parameter of QualitySettings is the quality check acceptance threshold, from 1.0 to 5.0, where 1.8 is recommended

DetectionSettings detectionSettings

Document detection settings for the camera. The DetectionSettings parameters are, respectively, the document acceptance threshold, in a value from 0.0 to 1.0 with 0.91 recommended, and the number of correct consecutive frames needed, where the recommended is 5

CaptureMode captureMode

Photo capture mode. It can be CaptureMode.AUTOMATIC for automatic capture or CaptureMode.MANUAL for the appearance of a button for the user to capture

DocumentDetectorCustomizationAndroid constructor

String styleResIdName

Name of the style resource that defines the colors of the DocumentDetector. For example, if you want to change the colors of the SDK, create a style in ROOT_PROJECT/android/app/src/main/res/values/styles.xml with the name R.style.my_custom_style following the template and parameterize "my_custom_style".

String layoutResIdName

Name of the resource layout that will replace the default DocumentDetector layout. For example, if you want to change the layout of the SDK, create a layout in ROOT_PROJECT/android/app/src/main/res/layout/my_custom_layout.xml following the template and parameterize "my_custom_layout".

String greenMaskResIdName

Name of the drawable resource to replace the default green mask. If you are going to use this parameter, use a mask with the same cutting area, it is important for the detection algorithm. For example, save the mask image in ROOT_PROJECT/android/app/src/main/res/drawable/my_custom_green_mask.png and parameterize "my_custom_green_mask".

String redMaskResIdName

Name of the drawable resource to replace the default red mask. If you are going to use this parameter, use a mask with the same cutting area, it is important for the detection algorithm. For example, save the mask image in ROOT_PROJECT/android/app/src/main/res/drawable/my_custom_red_mask.png and parameterize "my_custom_red_mask".

String whiteMaskResIdName

Name of the drawable resource to replace the default white mask. If you are going to use this parameter, use a mask with the same cutting area, it is important for the detection algorithm. For example, save the mask image in ROOT_PROJECT/android/app/src/main/res/drawable/my_custom_white_mask.png and parameterize "my_custom_white_mask".

SensorSettingsAndroid constructor

SensorLuminositySettingsAndroid sensorLuminositySettings

Brightness sensor settings to be applied in all steps of the SDK

SensorOrientationSettingsAndroid sensorOrientationSettings

Orientation sensor settings to be applied in all SDK steps

SensorStabilitySettingsAndroid sensorStabilitySettings

Orientation sensor settings to be applied in all SDK steps

SensorLuminositySettingsAndroid constructor

String messageResourceIdName

Name of the string resource to be shown when the room is dark. The default message is "Environment too dark". For example, if you want to show the String "Test", create a String in ROOT_PROJECT/android/app/src/main/res/values/strings.xml with name R.string.my_custom_luminosity_string and value "Test" and parametrize "my_custom_luminosity_string".

int luminosityThreshold

Lower threshold between acceptable/not acceptable brightness, in lx. The default is 5 lx

SensorOrientationSettingsAndroid constructor

String messageResourceIdName

Name of the string resource to be shown when the phone is not horizontal. The default message is "Cell phone is not horizontal". For example, if you want to show the String "Test", create a String in ROOT_PROJECT/android/app/src/main/res/values/strings.xml with the name R.string.my_custom_orientation_string and value "Test" and parametrize "my_custom_orientation_string".

double orientationThreshold

Lower threshold between correct/incorrect orientation, in m/s² variation from fully horizontal orientation. The default is 3 m/s².

SensorStabilitySettingsAndroid constructor

String messageResourceIdName

Name of the string resource to be shown when the phone is not stable. The default message is "Keep cell phone still". For example, if you want to show the String "Test", create a String in ROOT_PROJECT/android/app/src/main/res/values/strings.xml with name R.string.my_custom_stability_string and value "Test" and parametrize "my_custom_stability_string".

int stabilityStabledMillis

How many milliseconds the cell phone must stay at the correct threshold to be considered stable. The default is 2000 ms

double stabilityThreshold

Lower threshold between stable/unstable, in m/s² variation between the last two sensor collections. The default is 0.5 m/s².

iOS

DocumentDetectorIosSettings constructor

double detectionThreshold

Document acceptance threshold, in a value from 0.0 to 1.0. The default is 0.95

bool verifyQuality

Flag indicating whether you want to check the quality of the captured document

double qualityThreshold

Quality acceptance threshold, between 1.0 and 5.0. 1.8 is recommended for future OCR

DocumentDetectorCustomizationIos customization

Visual customization of the DocumentDetector

SensorSettingsIos sensorSettings

Custom sensor settings in iOS, null to disable

DocumentDetectorCustomizationIos constructor

String colorHex

SDK theme color. For example, if you want to use the color black, use "#000000".

String greenMaskImageName

Name of the image to replace the default green mask. Remember to add the image in Assets Catalog Document in your XCode project

String whiteMaskImageName

Name of the image to replace the default white mask. Remember to add the image in Assets Catalog Document in your XCode project

String redMaskImageName

Name of the image to replace the default red mask. Remember to add the image in Assets Catalog Document in your XCode project

String closeImageName

Name of the image to replace the SDK close button. Remember to add the image in Assets Catalog Document in your XCode project

bool showStepLabel

Flag indicating whether to show the label of the current step

bool showStatusLabel

Flag indicating whether to show the current status label

SensorSettingsIos constructor

SensorLuminositySettingsIos sensorLuminosity

Brightness sensor settings to be applied in all steps of the SDK

SensorOrientationSettingsIos sensorOrientation

Orientation sensor settings to be applied in all SDK steps

SensorStabilitySettingsIos sensorStability

Stability sensor settings to be applied in all SDK steps

SensorLuminositySettingsIos constructor

String message

String to be shown when the room is dark

double luminosityThreshold

Lower threshold between acceptable/not acceptable brightness. The default is -3

SensorOrientationSettingsAndroid constructor

String message

String to be shown when the cell phone is not horizontal

double orientationThreshold

Lower threshold between correct/incorrect orientation. Default is 0.3

SensorStabilitySettingsAndroid constructor

String message

String to be shown when the cell phone is not stable

double stabilityThreshold

Lower threshold between stable/unstable, in m/s² variation between the last two sensor collections. The default is 0.3 m/s².

Collecting the result

The DocumentDetector return object will have the result attribute that contains a string SUCCESS, FAILURE or CLOSED. The return will default to DocumentDetectorSuccess, DocumentDetectorFailure and DocumentDetectorClosed, respectively, for each of the cases.

DocumentDetectorSuccess

Field

Observation

List<Capture> captures

List of document captures

It will have the same length and order as the **List<DocumentDetectorStep> ** parameter

String type

Document type detected by the SDK itself, useful for integration with our external OCR route. For example, if you capture DocumentType.CNH_FRONT and DocumentType.CNH_BACK, this parameter will be "cnh".

Will be null if the SDK cannot check the document type or if detection is disabled

String trackingId

Identificador dessa execução em nossos servidores. Se possível, salve este campo e mande-o junto para nossa API. Assim, teremos mais dados de como o usuário se comportou durante a execução

Will be null if the user sets useAnalytics = false or the analytics calls do not work

Capture

Field

Observation

String imagePath

Full address of the image on the device

String imageUrl

URL of the image temporarily stored on CAF servers

Will be null if the SDK cannot check the quality or if the quality is disabled

String label

Label for detecting the capture. For example, if the capture refers to a DocumentType.RG_FRONT, this label can be "rg_front" or "rg_new_front", which refers to the new RG models

Will be null if the photo is collected at a stage where detection is disabled

double quality

Quality of the document photo, in a value from 1.0 to 5.0

Will be null if the photo is collected at a stage where quality checking is disabled

DocumentDtetectorFailure

Field

String message

Friendly message explaining why the SDK failed

String type

Fault type that shut down the SDK

The existing fault types are:

InvalidTokenReason: when the token entered is invalid. It should not occur in a production environment;
PermissionReason: when some mandatory permission was not granted by the user. It will only happen in a production environment if your app does not ask your user or the user manually disables it before starting;
NetworkReason: server connection failure. Will occur in production if the user's device is without internet;
ServerReason: failure in some request with our servers. It will occur in production only in case of our failure;
SecurityReason: when the device is not safe to run the SDK. If this failure occurs, let us know;
StorageReason: when the device does not have enough space to capture some photo. This can happen in production;
LibraryReason: when some internal failure made it impossible to run the SDK. It can occur due to configuration errors in the project, it should not occur in production;

DocumentDetectorClosed

Empty object indicating closure of the capture screen by the user.

Last updated 3 months ago