Search
⌃K
Links

DocumentDetector

Capture authentic, high-quality photos of user-submitted documents, allowing you to send them later for analysis in our API.

Supported documents

Currently, supported documents on Android are:
public enum Document {
RG_FRONT, // frente do RG, parte onde está a foto
RG_BACK, // verso do RG, onde está os dados
RG_FULL, // RG aberta, aparecendo tanto a frente quanto o verso
CNH_FRONT, // frente da CNH, parte onde está a foto
CNH_BACK, // verso da CNH, parte onde está a assinatura
CNH_FULL, // CNH aberta, aparecendo tanto a frente quanto o verso
CRLV, // CRLV
RNE_FRONT, // frente do RNE e RNM, onde estão os dados
RNE_BACK, // verso do RNE e RNM, onde está a foto
PASSPORT, // Passaporte, apenas um lado, mostrando todos os dados
CTPS_FRONT, // Frente da CTPS, onde contém a foto
CTPS_BACK, // Verso da CTPS, onde contém os dados
OTHERS, // outros documentos de identificação em geral, como RNE, Identidade Militar, OAB e CRLV
ANY; // permite o envio de qualquer tipo de documento, todos os citados acima, incluindo qualquer outro documento, pois não são feitas tipificações
}

SDK size

The SDK size is approximately 9.6 MB, which may decrease due to these elements.

Optimizing SDK size

If you want to reduce the DocumentDetector SDK size, add the following setting to your app-level build.gradle:
android {
defaultConfig {
ndk {
abiFilters 'armeabi-v7a', 'arm64-v8a'
}
}
}
This will shrink approximately 2 MB of the final app. According to TensorFlow documentation, this setting covers most modern devices.

Analytics

By default, our SDKs gather information about the user's environment and execution flows to map bugs and potential fraudsters to understand their behavior. We fully recommend keeping data-gathering activities, the only purpose of this is for us to obtain information to prevent potential frauds, but if you wish, you can disable it by adding the following parameter to the DocumentDetector constructor: .setAnalyticsSettings(boolean useAnalytics).

Runtime permissions

Permission
Reason
Required
CAMERA
To capture photos of the documents
Yes

Instantiating the SDK

First things first, instantiate an object of type DocumentDetector. This object will contain all your business rules for the SDK:
DocumentDetector mDocumentDetector = new DocumentDetector.Builder(String mobileToken)
// see table below
.build();
All parameters annotated with @Nullable can receive null values, useful if you want to configure only one of the parameters of the same method.

Builder method

Parameter
Required
String mobileToken
Token associated with your account, to use the SDK.
Yes.
.setDocumentSteps(DocumentDetectorStep[] documentSteps)
Defines the document capture flow as explained here​
Yes.
.setPeopleId(String peopleId)
User identifier for fraud profile identification purposes and to assist in the identification of Analytics logs in cases of bugs and errors.
No. Used only for analytics purposes.
.setAnalyticsSettings(boolean useAnalytics)
Enables/disables data gathering for analytics.
No. The default value is true.
.setCaptureStages(CaptureStage[] captureStages)
Configures the requirements for each capture stage. Typically ranging from the most demanding, requiring the highest quality, to the least demanding, with the lowest quality, as explained here.
No. See recommended configuration here​
.setPopupSettings(boolean show)
Enables/disables the popups displayed before each document capture.
No. The default value is true.
.setLayout(@Nullable @LayoutRes Integer layoutId)
Overrides the default SDK layout. Create a file in the layout folder of your project, copy this template and make the changes you want.
No. The default layout is this.
.setMask(MaskType type)
Set the mask design displayed during captures. There are three types:
  • MaskType.DEFAULT, with the dotted pattern in the document format;
  • MaskType.DETAILED, which shows an illustration of the requested document, along with the dotted mask;
  • MaskType.NONE, which completely removes the mask.
No. The default value is MaskType.DEFAULT.
.setMask(@DrawableRes Integer greenMask, @DrawableRes Integer whiteMask, @DrawableRes Integer redMask)
Allows full customization of the masks displayed during document capture. Three types are required, one for each document validation feedback during capture: SUCCESS (greenMask), NORMAL (whiteMask) e ERROR (redMask). Going with this option, use masks with the same detection area as the document, this is extremely important for the algorithm to perform validations during the capture.
No. See our mask templates to get the detection area:
​NORMAL​
​SUCCESS​
​ERROR​
.setStyle(@StyleRes int styleResourceId)
Set up a new style guideline for the SDK. Create a styles.xml file in your project with this template and customize it.
No. The default style is this.
.setAudioSettings(boolean enable)
Enables/Disables SDK audio playback.
No. The default value is true.
.setNetworkSettings(int requestTimeout)
Defines SDK's requests timeout.
No. The default value is 60 (seconds).
.setLuminositySensorSettings(@Nullable SensorLuminositySettings sensorLuminositySettings)
Defines luminosity sensor settings. Set null if you don't want to use this sensor.
No. The default settings are 5 (lx).
.setOrientationSensorSettings(@Nullable SensorOrientationSettings sensorOrientationSettings)
Defines orientation sensor settings. Set null if you don't want to use this sensor.
No. The default setting is 3 (m/s²).
.setStabilitySensorSettings(@Nullable SensorStabilitySettings sensorStabilitySettings)
Defines stability sensor settings. Set null if you don't want to use this sensor.
No. The default setting is time 2000 (ms) and threshold 0.5 (m/s²).
.setProxySettings(@Nullable ProxySettings proxySettings)
Defines proxy settings. Follow this guide.
No. The default setting is null.
.setPreviewSettings(@NonNull PreviewSettings previewSettings)
Enables/disables and allows the configuration of the visualization of the capture performed, requesting the user's confirmation to proceed.
No. The default is disabled.
.setAutoDetection(boolean enable)
Enables/disables auto-detection and sensor checks. Use false to disable all checks on the device. This way, all validations will be performed on the backend after the capture.
No. The default is true.
.setCurrentStepDoneDelay(boolean showDelay, int delay)
Delays 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.
No. The default is false.
.setMessageSettings(MessageSettings messageSettings)
Allows you to customize the messages displayed in the "status" balloon during the capture and analysis process.
No. The default is this.
.setGetImageUrlExpireTime(Time expireTime)
Allows you to customize the expiration time of the imageUrl. The method receives as a parameter the enum Time with the available times.
No. The default is Time.DEFAULT.
.enableSwitchCameraButton(boolean enable)
Enables/disables the button for the user to switch between the front and rear cameras.
No. The default is true.
.setResolutionSettings(Resolution resolution)
Allows you to set the capture resolution. The method takes as a parameter a Resolution that has the following options:
  • HD: 720x1280
  • FULL_HD: 1080x1920
  • QUAD_HD: 1440x2560
  • ULTRA_HD: 2160x3840
No. The default is Resolution.ULTRA_HD.
.setCompressSettings(@IntRange(from = 50, to = 100) int 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).
No. The default is 100.
.enableGoogleServices(boolean enable)
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.
No. The default is true.
.setUseEmulator(boolean use)
Allows the use of emulators when true. It is not recommended to enable this option, use it only for testing purposes.
No. The default is false.
.setUseRoot(boolean use)
Allows the use of root devices when true. It is not recommended to enable this option, use it only for testing purposes.
No. The default is false.
.setUseDeveloperMode(boolean use)
Enables the use of developer mode when true. It is not recommended to enable this option, use it only for testing purposes.
No. The default is false.
.setUseAdb(boolean use)
Enables Android Debug Bridge (ADB) debugging mode when true. It is not recommended to enable this option, use it only for testing purposes.
No. The default is false.
.setUseDebug(boolean use)
Allows you to use the app in debug mode when true. It is not recommended to enable this option, use it only for testing purposes.
No. The default is false.
.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".
Examples:
  • setGetImageUrlExpireTime("30m"): To set up minute(s) only
  • setGetImageUrlExpireTime("24h"): To set up hour(s) only
  • setGetImageUrlExpireTime("1h 10m"): To set hour(s) and minute(s)
  • setGetImageUrlExpireTime("10d"): To set up day(s)
No. The default is 3h.
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.
No. By default, this option is disabled, here is how to set it.
.setAllowedPassportCountriesList(CountryCodeList[] countryList)
Enables the option to allow passports from only a certain issuing country, or, a list of countries. See the complete list at: ISO 3166-1 alpha-3​
Example:
  • .setAllowedPassportCountriesList(new CountryCodesList[]{CountryCodesList.BRA})
No. Passports issued by any country are accepted by default.

DocumentDetectorStep

To create a capture flow, you will need to create an array of DocumentDetectorStep, where each element will be a capture step. To construct each DocumentDetectorStep object, you can enter the following elements:
DocumentDetectorStep detectorStep = new DocumentDetectorStep(Document.RG_FRONT);
Parameter
Required
Document document
Identifies which document you want to capture in the respective step. See supported document types here.
Yes.
.setStepLabel(@StringRes int stepLabel)
Defines text to be shown in the lower part of the layout.
No. There is a pattern by Document type.
.setIllustration(@StringRes int illustration)
Defines illustration to be shown in the popup prior to capture.
No. There is a pattern by Document type.
.setStepAudio(@RawRes int stepAudio)
Sets audio that will be played at the beginning of the step.
No. There is a pattern by Document type.
.setMask(@DrawableRes Integer whiteMaskResId, @DrawableRes Integer greenMaskResId, @DrawableRes Integer redMaskResId)
Sets the masks for each document type. Using this method overrides the masks defined in the .setMask method of DocumentDetector.Builder.
No. The default is set by the .setMask method of the DocumentDetector.Builder.

CaptureStage

To improve the client's UX, we recommend creating difficulty stages for the DocumentDetector. For this, we offer the CaptureStage object, where you can set the following parameters:
Parameter
Long durationMillis
Duration of the stage, in milliseconds. If you do not want a timeout, parameterize null.
boolean wantSensorCheck
Enables/Disables the use of sensors for capturing the photo.
QualitySettings qualitySettings
Document quality check settings. If you do not want to check the quality of the document, set null.
DetectionSettings detectionSettings
Settings for automatic document detection. If you do not want to use automatic detection, set null.
CaptureMode captureMode
Document capture mode, which can be CaptureMode.AUTOMATIC or CaptureMode.MANUAL. In manual capture, a button will be enabled for the user to perform the capture.
Since the .setCaptureStages parameter is not required, if it is not used, the DocumentDetector will use this default:
QualitySettings qualitySettings = new QualitySettings(1.8);
DetectionSettings detectionSettings = new DetectionSettings(0.95, 5);
​
new CaptureStage[]{
new CaptureStage(20000L, true, qualitySettings, detectionSettings, CaptureMode.AUTOMATIC),
new CaptureStage(15000L, false, qualitySettings, detectionSettings, CaptureMode.AUTOMATIC),
new CaptureStage(10000L, false, qualitySettings, detectionSettings, CaptureMode.MANUAL),
new CaptureStage(null, false, qualitySettings, null, CaptureMode.MANUAL)
}

QualitySettings

Parameter
Observarions
double threshold
Threshold that defines whether the document capture has quality or not.
Ranges from 1.0 to 5.0, where 1.8 is the recommended threshold.

DetectionSettings

Parameter
Observarions
double threshold
Threshold that defines whether or not the document displayed by the user is the document being requested.
A value between 0.0 and 1.0, where 0.95 is recommended.
int consecutiveFrames
Number of consecutive correct frames for document acceptance.
5 is recommended. The more frames, the longer it will take to detect the document.

UploadSettings

To enable the document upload functionality it is necessary to instantiate an object of type UploadSettings(boolean enable) and set its parameters:
Parameter
Required
.setEnable(Boolean enable)
Enables/disables this feature.
No. The default is true.
.setCompress(Boolean enable)
Enables/disables file compression before uploading.
No. The default is true.
.setFileFormats(FileFormat[] fileFormats)
Defines the file format(s) that will be accepted for upload.
No. By default .PDF, .JPG, .JPEG, .PNG, .HEIF are accepted.
.setMaxFileSize(Integer maxFileSize)
Sets the maximum KB limit of the file to upload.
No. The default limit is 20000 KB (20MB).
.setActivityLayout ( Integer activityLayout)
Defines the background layout of the document upload.
No.
.setPopUpLayout (Integer popUpLayout)
Defines the layout of the document upload request popup.
No.
Currently, the supported file formats are:
public enum FileFormat {
PNG("image/png"),
JPG ("image/jpg"),
JPEG ("image/jpeg"),
PDF("application/pdf"),
HEIF("image/heif");
}

MessageSettings

To use, simply instantiate a MessageSettings object and use the methods as needed for customization.
Method
Default value
.setPopupDocumentSubtitleMessage(@NonNull @StringRes Integer message)
Message displayed in the subtitle of the pop-up that brings the illustration of the document that is being requested for capture.
“Posicione o documento em uma mesa, centralize-o na marcação e aguarde a captura automática.”
.setFitTheDocumentMessage(Integer message)
Message telling you to fit the document to the mask.
"Encaixe o documento na marcação"
.setHoldItMessage(Integer message)
Message displayed at the moment the capture is being performed.
"Segure assim"
.setVerifyingQualityMessage(Integer message)
Message displayed when the SDK makes a request to the backend, checking for quality.
"Verificando qualidade…"
.setLowQualityDocumentMessage(Integer message)
Message displayed when the capture quality fails.
"Ops, não foi possível ler as informações. Por favor, tente novamente"
.setUploadingImageMessage(Integer message)
Message displayed when there is no quality check and the capture is being saved on the servers.
"Enviando imagem…"
.setShowOpenDocumentErrorMessage(boolean show, @Nullable Integer message)
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.
"Use o documento fechado e tente novamente"
.setWaitMessage(boolean show, @Nullable Integer message)
Message displayed when you start the camera.
"Aguarde..."
.setSensorLuminosityMessage(@NonNull @StringRes Integer message)
Message displayed when the brightness threshold is lower than expected.
"Ambiente muito escuro"
.setSensorOrientationMessage(@NonNull @StringRes Integer message)
Message displayed when the orientation threshold is lower than expected.
"Celular não está na vertical"
.setSensorStabilityMessage(@NonNull @StringRes Integer message)
Message displayed when the orientation threshold is lower than expected.
"Mantenha o celular parado"
.setWrongDocumentMessage_RG_FRONT(Integer message)
Message displayed when the front of the RG(Brazilian ID card) is displayed in a different flow than expected.
"Ops, esta é a frente do RG"
.setWrongDocumentMessage_RG_BACK(Integer message)
Message displayed when the RG(Brazilian ID card) version is displayed in a different flow than expected.
"Ops, este é o verso do RG"
.setWrongDocumentMessage_RG_FULL(Integer message)
Message displayed when the open RG(Brazilian ID card) is displayed in a different stream than expected.
"Ops, este é o RG aberto"
.setWrongDocumentMessage_CNH_FRONT(Integer message)
Message displayed when the front of the CNH(Brazilian driver's license) is displayed in a different stream than expected.
"Ops, esta é a frente da CNH"
.setWrongDocumentMessage_CNH_BACK(Integer message)
Message displayed when the version of the CNH(Brazilian driver's license) is displayed in a different stream than expected.
"Ops, este é o verso da CNH"
.setWrongDocumentMessage_CNH_FULL(Integer message)
Message displayed when the open CNH(Brazilian driver's license) is displayed in a different stream than expected.
"Ops, esta é a CNH aberta"
.setWrongDocumentMessage_CRLV(Integer message)
Message displayed when the CRLV(Brazilian Vehicle Registration and Licensing Certificate) is displayed in a different stream than expected.
"Ops, este é o CRLV"
.setWrongDocumentMessage_RNE_FRONT(Integer message)
Message displayed when the front of the RNE(National Registry of Foreigners) is displayed in a different stream than expected.
"Ops, esta é a frente do RNE"
.setWrongDocumentMessage_RNE_BACK(Integer message)
Message displayed when the back of the RNE(National Registry of Foreigners) is displayed in a different stream than expected.
"Ops, este é o verso do RNE"
.setPositiveButtonMessage(Integer message)
Allows for customization of the confirmation button message.
Não. O padrão é "Ok, entendi!"
.setUploadedImageIsTooLargeTitle
Sets the title of the upload popup when the uploaded file exceeds the maximum allowed size.
Não. O padrão é "Tamanho de foto excedido."
.setUploadedImageIsTooLargeMessage
Sets the upload popup message when the uploaded file exceeds the maximum allowed size.
Não. O padrão é "Parece que tamanho da foto que você escolheu excede o tamanho permitido. Tente enviar um novo arquivo mais leve."
.setUploadedImageHasInvalidFormatTitle
Sets the title of the upload popup when the format of the uploaded file is not valid.
Não. O padrão é "Formato inválido."
.setUploadedImageNotSupportedFormatMessage
Sets the upload popup message when the format of the uploaded file is not valid.
Não. O padrão é "Parece que o formato da sua foto não é suportado. Tente reenviar usando os formatos de JPG, PNG ou PDF."
.setUploadedImageGenericErrorTitle
Sets the generic error title for the upload popup.
Não. O padrão é "Ops, algo deu errado."
.setUploadedImageWrongMessage
Sets the generic error message for the upload popup.
Não. O padrão é "Parece que a foto não é a esperada. Envie um foto do tipo de documento escolhido."
.setUploadedImageLowQualityTitle
Sets the title of the upload popup when the quality of the uploaded image fails.
Não. O padrão é "Ops, qualidade baixa"
.setUploadedImageLowQualityMessage
Sets the upload popup message when the quality of the uploaded image fails.
Não. O padrão é "Parece que a qualidade da foto está muito baixa. Tente enviar uma foto com a qualidade maior."
.setUploadPopupLoadingMessage
Sets the message displayed in the upload popup while the file is being uploaded.
Não. O padrão é "Enviando sua foto"
Example
MessageSettings messageSettings = new MessageSetings()
.setFitTheDocumentMessage(R.string.exempleFit)
.setHoldItMessage(R.string.exempleHoldIt);

Security validations

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:
DocumentDetector.Builder("mobileToken")
.setUseEmulator(true)
.setUseRoot(true)
.setUseDeveloperMode(true)
.setUseAdb(true)
.setUseDebug(true)
.build();
Disabling security validations is recommended for testing purposes only. For publishing your application in production, we recommend using the default settings.

Starting Activity

After creating the DocumentDetector, start the DocumentDetectorActivity by passing this object as a parameter via extra intent:
Intent mIntent = new Intent(context, DocumentDetectorActivity.class);
mIntent.putExtra(DocumentDetector.PARAMETER_NAME, mDocumentDetector);
startActivityForResult(mIntent, REQUEST_CODE);

Getting the result

To get the DocumentDetectorResult object, which contains the captures taken by the SDK, override the onActivityResult method in the same Activity that you started the DocumentDetectorActivity:
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
if (requestCode == REQUEST_CODE){
if (resultCode == RESULT_OK && data != null){
DocumentDetectorResult mDocumentDetectorResult = (DocumentDetectorResult) data.getSerializableExtra(DocumentDetectorResult.PARAMETER_NAME);
// check mDocumentDetectorResult.getSDKFailure() to find out why the SDK was terminated
} else {
// the user closed the activity
}
}
super.onActivityResult(requestCode, resultCode, data);
}

DocumentDetectorResult

Parameter
Allow null
Capture[] captures
The array with the respective captures of the parameterized documents.
Yes, in case of error
String type
The class of the read document stream. This parameter is useful in an integration with our OCR route.
Yes, in case of an error or when you couldn't check the quality.
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 on how the user behaved during the execution.
Yes, if the user sets useAnalytics = false or the analytics calls do not work.
SDKFailure sdkFailure
Object that tells you the reason for the SDK shutdown. For more information, see here.
Yes, in case of success

Capture

Parameter
Allow null
String imagePath
Full path of the image on the user's device.
No.
String imageUrl
URL of the document on the CAF server.
No.
String label
Identification of the type of the captured document, within the following possibilities: ["blank", "cnh_back", "cnh_front", "cnh_full", "new_cnh_back", "new_cnh_froString imagePathString imageUrlString labelDouble qualitynt", "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"].
Yes, when you could not check the quality.
Double quality
Quality is inferred by the document quality algorithm when enabled. Ranges from 1.0 to 5.0.
Yes, when you could not check the quality.
int lensFacing
Defines the face of the camera that was used. Use DocumentDetectorResult.LENS_FACING_FRONT or DocumentDetectorResult.LENS_FACING_FRONT to validate.
No.