HomeAPISDK
Ask or search…
⌃K
Links
Comment on page

DocumentDetector

Plugin that calls native SDKs in Android and iOS. If you have any questions, please send an email to our Head of Mobile​
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 modified 10mo ago