DocumentDetector v7.x or below

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 3.3 MB, which may decrease due to these elements.

Runtime permissions

Permission	Reason	Required?
CAMERA	To capture photos of the documents.	Only for capture feature.
READ_EXTERNAL_STORAGE	To access the device external storage and select documents in the upload flow.	Only for upload feature.
READ_MEDIA_IMAGES	To access the device media storage and select documents in the upload flow.	Only for upload feature.
ACCESS_FINE_LOCATION	To collect connection data with the signal tower, for analytical purposes only.	No.

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 threshold between acceptable/unacceptable ambient brightness. Set null if you don't want to use this sensor.	No. The default settings are 5 (lx).
.setOrientationSensorSettings(@Nullable SensorOrientationSettings sensorOrientationSettings) Defines threshold between correct/incorrect device orientation. Higher the value more flexible it will be. 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.
.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.
.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.	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.
.setStage(CafStage stage) Allows you to choose the environment in wich the SDK will run (production, beta). The method takes as parameter an enum CafStage to select the environment:	No. The default is CafStage.PROD
Enum	Description
CafStage.PROD	Will use the Trust Platform production environment to register the SDK executions.
CafStage.BETA	Will use the Trust Platform beta environment to register the SDK executions.

Each environment (beta and production) requires its own specific mobileToken, generated in the Trust platform of the respective environment.

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 10000 KB (10MB).
.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 do arquivo excedido"
.setUploadedImageIsTooLargeMessage Sets the upload popup message when the uploaded file exceeds the maximum allowed size.	Não. O padrão é "Parece que o arquivo que você escolheu excede o tamanho permitido. Tente enviar um arquivo menor."
.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 do arquivo 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 o documento não é o esperado. Envie um arquivo com o tipo de documento solicitado."
.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 imagem documento está muito baixa. Tente enviar um arquivo com melhor qualidade."
.setUploadPopupLoadingMessage Sets the message displayed in the upload popup while the file is being uploaded.	Não. O padrão é "Enviando documento"

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_front", "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", "cin_front", "cin_back"].	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.