HomeAPISDK
Ask or search…
⌃K
Links
Comment on page

DocumentDetector

Supported documents

Currently, the supported documents in Android are: RG, CNH, RNE, CRLV, CTPS, Passport. If you have any suggestions for other documents, please contact us!

Privacy Policy and Terms & Conditions of Use

When using our plugin, please make sure that you agree with our Privacy Policy and our Terms and Conditions of Use.

Analytics

Our SDKs by default collect information about the user and running environment to better map fraudsters and understand their behaviors. We recommend keeping this collection active as the sole purpose of this data is for fraud reduction, but if you wish you can disable it by the **.setAnalyticsSettings(bool useAnalytics) ** parameter.

Pre-requirements

Minimum configuration
Version
Flutter
1.12+
Dart
2.12+
Minimum Android API
21+
Compile SDK Version
33
iOS
11.0+
Xcode
13.4.1+
If you use Dart in a version below 2.12, check the compatible version here.

Settings

Android

In the file ROOT_PROJECT/android/app/build.gradle, add:
android {
​
...
​
dataBinding.enabled = true
compileOptions {
sourceCompatibility = JavaVersion.VERSION_1_8
targetCompatibility = JavaVersion.VERSION_1_8
}
aaptOptions {
noCompress "tflite"
}
}
// To perform layout customization from the SDK import the following libraries
dependencies {
implementation "androidx.camera:camera-view:1.2.0-alpha02"
implementation 'com.combateafraude.sdk:document-detector:6.39.6'
// Native Android SDK that the plugin implements
// design libraries you will use in your layout (these are used in our example template for customization)
implementation 'com.google.android.material:material:1.2.1'
implementation 'androidx.constraintlayout:constraintlayout:2.0.2'
}

iOS

In the ROOT_PROJECT/ios/Podfile, add to the end of the file:
source 'https://github.com/combateafraude/iOS.git'
source 'https://cdn.cocoapods.org/' # or 'https://github.com/CocoaPods/Specs' if the CDN is down
Finally, add the permissions to the file ROOT_PROJECT/ios/Runner/Info.plist:
<key>NSCameraUsageDescription</key>
<string>To read the documents</string>
​
// Required only for the document upload flow
<key>NSPhotoLibraryUsageDescription</key>
<string>To select images</string>
To enable text and voice in Portuguese, in your project, in the ROOTPROJECT/ios directory, open the .xcworkspace file in Xcode and add in Project > Info > Localizations the language Portuguese (Brazil).

Flutter

Add the plugin to your ROOT_PROJECT/pubspec.yaml file:
dependencies:
document_detector:
git:
url: https://github.com/combateafraude/Flutter.git
ref: document-detector-v5.26.4

Runtime Permissions

Permission
Motive
Required?
CAMERA
To capture the document photo(s)
Yes

Utilization

DocumentDetector documentDetector = new DocumentDetector(mobileToken: mobileToken);
documentDetector.setDocumentFlow(List<DocumentDetectorStep> documentSteps);
​
// Other customization parameters
​
DocumentDetectorResult documentDetectorResult = await documentDetector.start();
​
if (documentDetectorResult is DocumentDetectorSuccess) {
// The SDK was closed successfully and the pictures of the documents were captured
} else if (documentDetectorResult is DocumentDetectorFailure) {
// The SDK was closed due to some glitch and the document pictures were not captured
} else {
// The user simply closed the SDK, with no result
}

Disabling Security Validations for Testing

We are constantly taking actions to make the product more and more secure, mitigating a number of attacks observed in the capture process and, consequently, reducing as many possible identity frauds as possible. 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:
DocumentDetectorAndroidSettings androidSettings =
DocumentDetectorAndroidSettings(
emulatorSettings: true,
rootSettings: true,
useDeveloperMode: true,
useAdb: true,
useDebug: true,
);
documentDetector.setAndroidSettings(androidSettings);
Attention! Disabling security validations is recommended for test environments only. For publishing your application in production, we recommend using the default settings.

General customizations

DocumentDetector
.setPeopleId(String peopleId)
CPF of the user who is using the plugin to be used for fraud detection via analytics
.setAnalyticsSettings(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
.setPopupSettings(bool show)
Change the setting for the inflated popups before each document. The default is true
.enableSound(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
.setAutoDetection(bool enable)
Enables/disables auto detection and sensor checks. Use false to disable all checks on the device. Thus, all validations will be performed on the backend after the capture. Default is true
.setCurrentStepDoneDelay(bool showDelay, int delay)
Delay the activity after the completion of each step. This method can be used to display a success message on the screen itself after the capture, for example. Default is false
.setMessageSettings(MessageSettings messageSettings)
Allows you to customize messages displayed in the "status" balloon during the capture and analysis process.
.setGetImageUrlExpireTime(String expireTime)
Sets the time the image URL will last on the server until it is expired. Expect to receive a time interval between "30m" to "30d". The default is 3h
.setAndroidSettings(DocumentDetectorAndroidSettings androidSettings)
Customizations only applied on Android
.setIosSettings(DocumentDetectorIosSettings iosSettings)
Customizations only applied on iOS
.setUploadSettings(UploadSettings uploadSettings)
Define the settings for uploading documents. By enabling this option, the SDK flow will prompt the user to upload the document files instead of capturing them with the device's camera. This option also includes document quality checks. By default, this flow option is not enabled
.setStage(String stage)
Allows you to choose the environment in wich the SDK will run (production or beta). The expected String values are: "PROD" and "BETA". This setting is not mandatory, by default the SDK will use the production environment.
Each environment (beta and production) requires its own specific mobileToken, generated in the Trust platform of the respective environment.
|
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
UploadSettings constructor
bool compress
Enables/disables file compression before uploading. Default is true
int maxFileSize
Sets the maximum size in KB of the file to upload. The default limit is 20000 KB (20MB)
List<String> fileFormats
Defines the file format(s) that will be accepted for upload. By default it accepts: .PDF , .JPG, .JPEG, .PNG, .HEIF
String activityLayout
Sets the background layout of the document upload
String popUpLayout
Sets the layout of the document upload request popup
ShowPreview
How to Modify: If you want to modify the selected text, modify the String with the message you want to use.
bool show
Preview Enable/Disable
String title
Title
String subTitle
Subtitle
String confirmLabel
Confirmation Pushbutton Text
String retryLabel
Retrieve Capture Button Text
Example of use
ShowPreview showPreview = new ShowPreview(
show: true,
title: "Was the photo okay?",
subtitle: "See if the photo is sharp",
confirmLabel: "Yes, it was good!",
retryLabel: "Take out again");
documentDetector.setShowPreview(showPreview);
MessageSettings
How to Modify: If you want to modify the selected text, modify the String with the message you want to use.
String? waitMessage
Default: "Please Wait..."
String? fitTheDocumentMessage
Default: "Fit the document on the markup"
String? holdItMessage (Android only)
Default: "Hold like this"
String? verifyingQualityMessage
Default: "Checking quality..."
String? lowQualityDocumentMessage
Default: "Ops, could not read the information. Please try again".
String? uploadingImageMessage
Default: "Sending image..."
boolean? showOpenDocumentMessage
Default: true
String? openDocumentWrongMessage
Default: "Close your document and try again"
String? documentNotFoundMessage
Padrão: "Didn't found a document"
String? sensorLuminosityMessage
Default: "Area near you is too dark".
String? sensorOrientationMessage
Default: "The device is not on the horizontal”
String? sensorStabilityMessage
Default: "Keep the device still”
String? unsupportedDocumentMessage
Default: "Ops, it seems that this document is not supported. Contact us!"
String? popupDocumentSubtitleMessage
Default: "Dispose the document in a desk, centralize it on the markup and hold the automatic capture."
String? setPositiveButtonMessage
Pattern: "OK, understood!"
String? wrongDocumentMessage_RG_FRONT (Android only)
Default: "Ops, this is the RG's Front"
String? wrongDocumentMessage_RG_BACK (Android only)
Default: "Ops, this is the RG's Back".
String? wrongDocumentMessage_RG_FULL (Android only)
Default: "Ops, this is the RG Opened"
String? wrongDocumentMessage_CNH_FRONT (Android only)
Default: "Ops, this is the CNH's Front"
String? wrongDocumentMessage_CNH_BACK (Android only)
Default: "Ops, this is the CNH's Back"
String? wrongDocumentMessage_CNH_FULL (Android only)
Default: "Ops, this is the CNH Opened"
String? wrongDocumentMessage_CRLV (Android only)
Default: "Ops, this is the CRLV".
String? wrongDocumentMessage_RNE_FRONT (Android only)
Default: "Ops, this is the RNE's Front"
String? wrongDocumentMessage_RNE_BACK (Android only)
Default: "Ops, this is the RNE's Back"
Example of use
MessageSettings messageSettings = new MessageSettings(
fitTheDocumentMessageResIdName: "Example message",
holdItMessageResIdName: "Example message",
verifyingQualityMessageResIdName: "Example message"
lowQualityDocumentMessageResIdName:"Example message" ,
uploadingImageMessageResIdName:"Example message",
openDocumentWrongMessage: "Example message",
showOpenDocumentMessage: true);
documentDetector.setMessageSettings(messageSettings);

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 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.
Integer compressQuality
Allows you to configure the quality in the compression process. By default, all captures go through compression. The method expects values between 50 and 100 as a parameter, where 100 is the best quality compression (recommended). The default is 100
bool enableSwitchCameraButton
Allows you to enable or disable the reverse camera button. The default is True
Resolution resolution
Allows you to set the capture resolution. The method takes as parameter a Resolution that provides the options HD, FULL_HD, QUAD_HD and ULTRA_HD. The default is Resolution.ULTRA_HD
bool enableGoogleServices
Allows you to enable/disable features of the SDK that consume GoogleServices in the SDK, we do not recommend disabling the services because of the loss of security. Default is True
bool enableEmulator
Allows the use of emulator when true
bool enableRootDevices
Allows use of root devices when true
bool useDebug
Enables/disables the use of the app in debug mode. Default is false
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 to set if this stage enable/disable sensors validations (luminosity, orientation and stability)
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". Check the import libraries mentioned here​
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".
MaskType maskType
Defines the type of mask used in the captures. There are three types: MaskType.DEFAULT, with the dotted pattern in the document format; MaskType.DETAILED, which displays an illustration of the requested document, along with the dotted mask; MaskType.NONE, which removes the mask entirely. The default is MaskType.DEFAULT
SensorSettingsAndroid constructor
SensorLuminositySettingsAndroid sensorLuminositySettings
Settings of the luminosity sensor 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
int luminosityThreshold
Lower threshold between acceptable/not acceptable brightness, in lx. The default is 5 lx
SensorOrientationSettingsAndroid constructor
double orientationThreshold
Lower threshold between correct/incorrect orientation, in m/s² variation from fully horizontal orientation. The default is 3 m/s².
SensorStabilitySettingsAndroid constructor
int stabilityStabledMillis
How many milliseconds the mobile 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 verify 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
Bool enableManualCapture
Enables manual capture mode
double timeEnableManualCapture
Time to enable the manual capture button
double compressQuality
Allows you to set the quality in the compression process. By default all captures are compressed. The method expects values between 0 and 1.0 as a parameter, 1.0 being the best quality compression (recommended).The default is 1.0
String resolution
Allows setting the capture resolution. The method takes as parameter a String IosResolution (default is hd1280x720), which has the following options:
Resolution
Description
low
Specifies appropriate capture settings for output video and audio bit rates suitable for 3G sharing
medium
Specifies the appropriate capture settings for the output video and audio bitrates suitable for sharing over WiFi
high
Specifies appropriate capture settings for high-quality video and audio output
photo
Specifies appropriate capture settings for high-resolution photo quality output
inputPriority
Specifies appropriate capture settings for high-resolution photo quality output
hd1280x720
Specifies the appropriate capture settings for video output at 720p quality (1280 x 720 pixels)
hd1920x1080
Capture settings suitable for 1080p (1920 x 1080 pixels) quality video output
hd4K3840x2160
Capture settings suitable for 2160p (3840 x 2160 pixels) quality video output
DocumentDetectorCustomizationIos constructor
String colorHex
The SDK's 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's 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
double? buttonSize
Value that sets the size of the "close" button in the SDK
String? buttonContentMode
Attribute that defines the content mode of the "close" button in the SDK. Choose from these values.
SensorSettingsIos constructor
SensorLuminositySettingsIos sensorLuminosity
Settings of the luminosity sensor 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
double luminosityThreshold
Threshold between acceptable/unacceptable ambient brightness. The default is -3
SensorOrientationSettingsAndroid constructor
double orientationThreshold
Threshold between correct/incorrect device orientation. Higher the value more flexible it will be. Default value is 3 m/s².
SensorStabilitySettingsAndroid constructor
double stabilityStabledMillis
Time between sensor's collections. The default is 2000 ms.
double stabilityThreshold
Threshold between stable/unstable, in m/s² variation between the last two sensor collections. The default is 0.5 m/s².

Collecting the result

The DocumentDetector return object is of abstract type DocumentDetectorResult. It can be an instance of DocumentDetectorSuccess, DocumentDetectorFailure or DocumentDetectorClosed.

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
Identifier of this execution 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
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 in the CAF servers
Will be null if the SDK cannot check the quality or if the quality is disabled
String label
Detection label of 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
Type of fault 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 occur in a production environment if your app does not ask the user or the user manually disables it before starting;
  • NetworkReason: server connection failure. It will occur in production if the user's device is not connected to the Internet;
  • ServerReason: failure in some request to our servers;
  • SecurityReason: when the device is not safe to run the SDK;
  • StorageReason: when the device does not have enough space to capture a photo. This can happen in production;
  • LibraryReason: when some internal failure made it impossible to execute the SDK. It may occur due to project configuration errors, and should not occur in production;

Customizing iOS views

For iOS customization, it is necessary that the Flutter plugins are added locally to the project. The customization is done natively with the ViewCode approach.
****Click here for an example with a guide to using this feature.
Last modified 4mo ago