DocumentDetector v7.x and above
Requirements
Flutter
1.20+
Dart
>=2.15.0 <4.0.0
minSdk
26
compileSdk
34
iOS Target
13.0+
Xcode
15.4+
Swift
5.3.2+
Native SDKs dependencies
dependencies {
// Basic
implementation "androidx.appcompat:appcompat:1.1.0"
// Design
implementation "com.google.android.material:material:1.2.1"
implementation "androidx.constraintlayout:constraintlayout:2.0.1"
// Document detection
implementation "org.tensorflow:tensorflow-lite:2.11.0"
implementation "org.tensorflow:tensorflow-lite-support:0.4.3"
// SecurityProvider
implementation "com.google.android.gms:play-services-basement:18.3.0"
// HTTP and deserializer
implementation "com.squareup.retrofit2:retrofit:2.9.0"
implementation "com.squareup.retrofit2:converter-gson:2.9.0"
implementation "com.squareup.okhttp3:okhttp:4.9.3"
implementation "com.squareup.okhttp3:okhttp-tls:4.9.3"
//exifInterface
implementation "androidx.exifinterface:exifinterface:1.0.0"
// CameraX core library using the camera2 implementation
// The following line is optional, as the core library is included indirectly by camera-camera2
implementation "androidx.camera:camera-core:1.1.0"
implementation "androidx.camera:camera-camera2:1.1.0"
// If you want to additionally use the CameraX Lifecycle library
implementation "androidx.camera:camera-lifecycle:1.1.0"
// If you want to additionally use the CameraX View class
implementation "androidx.camera:camera-view:1.1.0"
// Root Checks
implementation "com.scottyab:rootbeer-lib:0.0.8"
// Commons Imaging (for Images, EXIF data and so on. previously known as Apache Commons Sanselan)
implementation "org.apache.commons:commons-imaging:1.0-alpha3"
// Kotlin
implementation "androidx.core:core-ktx:1.7.0"
implementation "org.jetbrains.kotlin:kotlin-stdlib:1.5.31"
}
Runtime permissions
These are the Android's runtime permissions:
CAMERA
To capture photos of the documents
Only required in camera capture stream
READ_EXTERNAL_STORAGE
To access the device external storage and select documents in the upload flow. This permission is only required for versions lower than API33
Only required in the upload stream
Platform Configurations
If your version of Gradle is earlier than 7, add these lines to your build.gradle.
allprojects {
repositories {
...
maven { url 'https://repo.combateafraude.com/android/release' }
maven { url 'https://jitpack.io' }
}}If your version of Gradle is 7 or newer, add these lines to your settings.gradle.
dependencyResolutionManagement {
repositories {
...
maven { url 'https://repo.combateafraude.com/android/release' }
maven { url 'https://jitpack.io' }
}
}Add support for Java 8 (skip this code if Java 8 is enabled), and TensorFlow Model to your build.gradle file.
android {
...
aaptOptions {
noCompress "tflite"
}
compileOptions {
sourceCompatibility = JavaVersion.VERSION_1_8
targetCompatibility = JavaVersion.VERSION_1_8
}
}To customize the primary color of the SDK, you need to ensure that the Material Design library is imported in your app. Add the following dependency to your build.gradle file:
dependencies {
...
implementation 'com.google.android.material:material:1.9.0'
}Supported Documents
Currently, supported documents are:
enum DocumentType {
rgFront, // front of RG (where the photo is located)
rgBack, // back of RG
rgFull, // RG opened (showing front and back together)
cnhFront, // front of CNH (where the photo is located)
cnhBack, // back of CNH
cnhFull, // CNH opened (showing front and back together)
crlv, // CRLV
rneFront, // front of RNE or RNM
rneBack, // back of RNE or RNM
passport, // passport (showing the photo and data)
ctpsFront, // front of CTPS (where the photo is located)
ctpsBack, // back of CTPS
any; // allows you to send any type of document, all those mentioned above, including any other document
}Instantiating the SDK
To create a DocumentDetector instance, two required parameters must be provided:
mobileToken
Usage token associated with your CAF account
captureFlow
Defines the document capture flow. Create a List<DocumentCaptureFlow> to configure each capture step.
DocumentCaptureFlow
Each DocumentCaptureFlow element from the list will be a capture step.
The DocumentCaptureFlow class have the following configurations:
DocumentType documentType
DocumentType documentTypeIdentifies which document will be requested for capture in the respective step. You can choose from the Supported Documents list.
InstructionalPopupSettingsAndroid? androidCustomization
InstructionalPopupSettingsAndroid? androidCustomizationCustomize the instructional popup document illustration and label for Android devices.
String? documentLabel
Change the document label displayed in the popup. To customize this, you just have to provide a String element.
String? documentIllustration
Change the document illustration displayed in the popup. To customize this, you must provide the name of the file with the custom illustration you created in the res/drawable folder of your Android app.
InstructionalPopupSettingsIOS? iOSCustomization
InstructionalPopupSettingsIOS? iOSCustomizationCustomize the instructional popup document illustration and label for iOS devices.
String? documentLabel
Change the document label displayed in the popup. To customize this, you just need to provide a String element.
String? documentIllustration
Change the document illustration displayed in the popup. To customize this, you must provide the name of the Image Set with the custom illustration you created in the Asset Catalog of you iOS app.
Implementation Example
This is an example of how to instantiate the SDK and capture its results:
List<DocumentCaptureFlow> cnhFlow = [
DocumentCaptureFlow(documentType: DocumentType.cnhFront),
DocumentCaptureFlow(documentType: DocumentType.cnhBack)
];
DocumentDetector documentDetector =
DocumentDetector(mobileToken: mobileToken, captureFlow: cnhFlow);
// Your SDK customization options
try {
DocumentDetectorEvent event = await documentDetector.start();
if (event is DocumentDetectorEventSuccess) {
// The SDK completed successfully, and the document pictures were captured.
resultEvent = "SUCCESS";
resultDescription = "Document Type: ${event.documentType}\n\n";
// Use `event.captures` to get the details of each document captured
for (Capture capture in event.captures!) {
resultDescription += "#NEW CAPTURE\n";
resultDescription += capture.label != null
? "Document Label: ${capture.label!}\n"
: "empty\n";
resultDescription += capture.quality != null
? "Image Quality: ${capture.quality}\n"
: "empty\n";
resultDescription += capture.imagePath != null
? "File path on device: ${capture.imagePath!}\n"
: "empty\n";
resultDescription += capture.imageUrl != null
? "File URL: ${capture.imageUrl!.split("?")[0]}\n"
: "empty\n";
}
} else if (event is DocumentDetectorEventFailure) {
// The SDK did not complete successfully, and a failure occurred during the process.
resultEvent = "FAILURE";
resultDescription = event.securityErrorCode != null
? "Security code: ${event.securityErrorCode}\n"
: "none\n";
resultDescription += event.errorMessage != null
? "Failure Description: ${event.errorMessage}\n"
: "empty\n";
} else if (event is DocumentDetectorEventClosed) {
// The SDK was closed, the user closed the document capture process.
resultEvent = "CLOSED";
resultDescription = "User closed document capture flow";
}
} on PlatformException catch (e) {
// If an internal error occurs during the native bridge mapping, you can catch the exception this way.
resultEvent = "Error";
resultDescription = "Error starting DocumentDetector: ${e.message}";
}DocumentDetector options
DocumentDetectorEvent Results
DocumentDetectorEvent is an abstract class representing different types of events.
It is used to create an instance of one of the event subclasses based on a map input, which comes from the SDK's result.
Depending on the event type, it creates an instance of either DocumentDetectorEventClosed, DocumentDetectorEventSuccess, or DocumentDetectorEventFailure. If the event is not recognized, it throws an internal exception.
This setup allows for a structured and type-safe way to handle different outcomes of the document capture process in the SDK.
try {
DocumentDetectorEvent event = await documentDetector.start();
if (event is DocumentDetectorEventSuccess) {
// The SDK completed successfully, and the document pictures were captured.
for (Capture capture in event.captures!) {
// Use `event.captures` to get the details of each document captured
}
} else if (event is DocumentDetectorEventFailure) {
// The SDK did not complete successfully, and a failure occurred during the process.
} else if (event is DocumentDetectorEventClosed) {
// The SDK was closed, the user closed the document capture process.
}
} on PlatformException catch (e) {
// If an internal error occurs during the native bridge mapping, you can catch the exception this way.
}DocumentDetectorEventClosed
DocumentDetectorEventClosedThis class represents an event where the document capture was closed by the user, either by pressing the close button at the top right, or sending the app to the background.
DocumentDetectorEventSuccess
DocumentDetectorEventSuccessThis class represents a successful document capture event. The user document has been successfully captured, and the URLs for download the captures have been returned. It includes:
String? documentType
String? documentTypeThe type of the document captured
String? trackingId
String? trackingIdAn ID for tracking the capture execution.
DocumentDetectorEventFailure
DocumentDetectorEventFailureThis class represents a failure in the document capture process. The user document hasn't been successfully captured, the errorType and errorMessage parameter contains the failure reason. It includes:
String? errorType
String? errorTypeInformation on the type of error returned by the SDK. Below are the types of errors and their causes:
AvailabilityReason
The SDK is not yet available for use. The errorMessage parameter will bring more instructions.
The device's internal storage is full when installing the app, and the face detection template cannot be installed together.
InvalidTokenReason
The token entered is not valid for the corresponding product.
If you are using an expired or non-existent token.
LibraryReason
When an SDK internal library cannot be started.
Forgetting to set the aaptOptions noCompress configuration will lead to this failure in the DocumentDetector.
NetworkReason
Internet connection failure.
User was without internet during the SDK execution.
PermissionReason
You are missing some mandatory permission to run the SDK.
Start SDK without camera permission granted.
SecurityReason
When the SDK cannot be started due to a security reason.
When the device is rooted. See security error code for more reasons.
ServerReason
When an SDK request receives a status code of failure.
If an internal API is unstable.
StorageReason
There is no space on the user device's internal storage.
When there is no space on the internal storage while capturing the document photo.
String? errorMessage
String? errorMessageA message describing the error.
int? securityErrorCode
int? securityErrorCodeAn error code specific to Android, indicating the type of security validation failure:
100- blocking emulated devices;200- blocking rooted devices;300- blocking devices with developer options enabled;400- blocking devices with ADB enabled;500- blocking devices with debugging enabled;
Last updated