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](https://github.com/combateafraude/public-docs/blob/docs-sdks/analytics.md) 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. | |.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. | |.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..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:
| |.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. | |.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.
.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.
.setStabilitySensorSettings(@Nullable SensorStabilitySettings sensorStabilitySettings)
Defines stability sensor settings. Set null if you don't want to use this sensor.
.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. See the available attributes here.
| No. | |.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: 720x1280FULL\_HD: 1080x1920QUAD\_HD: 1440x2560ULTRA\_HD: 2160x3840.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.
.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.
.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.
.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.
.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.
.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) onlysetGetImageUrlExpireTime("24h"): To set up hour(s) onlysetGetImageUrlExpireTime("1h 10m"): To set hour(s) and minute(s)setGetImageUrlExpireTime("10d"): To set up day(s).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. See how to set it here.
| No. By default, this option is disabled. | |.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}).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:
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.
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.
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: ```java 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** ```java 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: ```java DocumentDetector.Builder("mobileToken") .setUseEmulator(true) .setUseRoot(true) .setUseDeveloperMode(true) .setUseAdb(true) .setUseDebug(true) .build(); ``` {% hint style="warning" %} Disabling security validations is recommended **for testing purposes only**. For publishing your application in production, we recommend using the default settings. {% endhint %} ## Starting Activity After creating the **`DocumentDetector`**, start the **`DocumentDetectorActivity`** by passing this object as a parameter via extra intent: ```java 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`**: ```java @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"].
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.