Comment on page

Customization

Learn how to customize our SDK and make it look like your app.

Custom layout creation
To create a new layout we recommend that you use the default templates from the SDKs (DocumentDetector, PassiveFaceLiveness, FaceAuthenticator), and make the desired changes.
Don't forget to have DataBinding enabled in your project as instructed in the "Getting Started" section
Step-by-step
1.Declare the dependency on CameraView in your app-level gradle file.
// CameraX core library using the camera2 implementation
implementation "androidx.camera:camera-view:1.0.0-alpha24"
  2. Create a layout file in your project's layout directory using the CAF template.
  3. Refer to the corresponding ViewModel for each SDK in your layout file. Example:
<layout>
    <data>
        <import type="android.view.View"/>
        <variable
            name="viewModel"
            type="com.combateafraude.documentdetector.controller.viewmodel.SDKViewModel" />
    </data>
    ...
</layout>
  4. Create your views, and parameterize the visibility and call methods of the ViewModel of each corresponding SDK according to the following tables. Example:
<layout>
...
    <androidx.camera.view.PreviewView
        android:id="@id/cameraImageView"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:visibility="@{viewModel.cameraVisibility ? View.VISIBLE : View.GONE}"
    />
    ...
</layout>
Variables and methods used in layout
All the methods and variables described below are accessed from the SDKViewModel class.
Methods
Method
Description
Return
SDK
takePhoto()
Responsible for initiating image capture in MANUAL mode
Void
DocumentDetector, PassiveFaceLiveness
close()
Responsible for closing the SDK.
Void
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
switchCamera()
Responsible for reversing the camera.
Void
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
State variables
The Layout used in the SDK is composed of several state variables, these variables are responsible for identifying the state that the SDK is in at each moment of its execution:
Variable
Description
Type
SDK
loadingStatus
Indicates the 'loading' state
Boolean
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
readyToCaptureStatus
Indicates that the SDK is ready to capture, after performing all validations for sensors, framing, face, etc.
Boolean
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
stepDoneSuccessfullyStatus
Indicates that the capture step ended successfully
Boolean
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
validationFailureStatus
Indicates if there are any faulty sensor checks, quality, framing, face distance, etc.
Boolean
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
validationFailureId
Indicates what type of error has occurred. See the table below
ValidationFailure
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
captureModeStatus
Indicates the capture mode enabled. May vary between AUTOMATIC and MANUAL
CaptureMode
DocumentDetector, PassiveFaceLiveness
maskStatus
Indicates the status of the mask. Can range from NORMAL, SUCCESS to ERROR
Mask
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
maskLayout
Responsible for returning the Drawable Resource Id used to define the mask.
Integer
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
previousStepName
Name of the previous step that was performed. If not, the value will be null. Example: Back of ID.
String
DocumentDetector
Visibility variables
Variable
Description
Type
SDK
popUpVisibility
Indicates the visibility of the step initialization popup
Boolean
DocumentDetector
manualCaptureButtonVisibility
Indicates visibility of the manual capture button
Boolean
DocumentDetector, PassiveFaceLiveness
switchCameraButtonVisibility
Indicates the visibility of the reverse camera button
Boolean
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
statusVisibility
Responsible for the visibility of the SDK status message.
Boolean
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
statusMessage
Returns the status message. Customize with MessageSettings
String
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
cameraVisibility
Responsible for camera visibility.
Boolean
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
maskVisibility
Indicates mask visibility.
Boolean
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
switchButtonVisibility
Responsible for the visibility of the camera flip button.
This variable has been deprecated, we recommend using the switchCameraButtonVisibility variable.
Boolean
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
serverRequesting
Responsible for the visibility of the loading displayed by the SDK.
This variable has been deprecated, we recommend using the loadingStatus variable.
Boolean
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
buttonVisibility
Sets the visibility of the manual capture button.
This variable has been deprecated, use manualCaptureButtonVisibility.
Boolean
DocumentDetector, PassiveFaceLiveness
ValidationFailure
Each SDK contains a number of validation errors that can occur while running. These mostly generate the "error mask" state and prevent the capture from being performed:
Error
Description
SDK
SENSOR_LUMINOSITY_FAILURE
Brightness sensor. The environment is too dark
DocumentDetector, PassiveFaceLiveness
SENSOR_ORIENTATION_FAILURE
Orientation sensor. Device not in correct position
DocumentDetector, PassiveFaceLiveness
SENSOR_STABILITY_FAILURE
Stability sensor. The device is in motion
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
FRAMING_FAILURE
Document or face-framing
DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
EYES_CLOSED_FAILURE
A face with closed eyes was identified
PassiveFaceLiveness, FaceAuthenticator
FACE_NOT_FOUND
No face was found
PassiveFaceLiveness, FaceAuthenticator
FACE_TOO_FAR
Face too far away.
PassiveFaceLiveness, FaceAuthenticator
FACE_TOO_CLOSE
Very close face.
PassiveFaceLiveness, FaceAuthenticator
ANGULATION_X_FAILURE
Incorrect face angle on the X axis.
PassiveFaceLiveness
ANGULATION_Y_FAILURE
Incorrect face angle on the Y axis.
PassiveFaceLiveness
ANGULATION_Z_FAILURE
Incorrect face angle on the Z axis.
PassiveFaceLiveness
MULTIPLE_FACES_FAILURE
Multiple faces detected.
PassiveFaceLiveness, FaceAuthenticator
QUALITY_FAILURE
Quality of the document capture is too low.
DocumentDetector
LIVENESS_FAILURE
Error in the proof of life. It is a probable fraud attempt
PassiveFaceLiveness, FaceAuthenticator
Using layout in Builder
After creating the desired files, create an object of type DocumentDetector. This object is for you to configure all your business rules for the SDK, including the interface customization attributes:
DocumentDetector mDocumentDetector = new DocumentDetector.Builder(String mobileToken)
    // see table below
    .build();
Builder method
Parameter
Required
.setLayout(@LayoutRes Integer layoutId)
Replaces the default SDK layout. Create a file in your project's layout folder, copy one of these layout templates, according to the SDK you are integrating, DocumentDetector, PassiveFaceLiveness, FaceAuthenticator, and make the desired changes.
No. It follows the standard of each SDK:
​DocumentDetector​
​PassiveFaceLiveness​
​FaceAuthenticator​
.setStyle(@StyleRes int styleResourceId)
Replaces the SDK's default style. In your project's styles.xml file, copy this template and edit it.
No. This is the default, for all SDKs
.setMask(@DrawableRes Integer greenMask, @DrawableRes Integer whiteMask, @DrawableRes Integer redMask)
Replaces the masks for capturing a document or face: SUCCESS, NORMAL, and FAIL, in that order. If you use this option, use masks with the same detection area of the document and face, as this region is very important for the algorithm to capture.
No. The defaults are found here:
​Mask for documents​
​Face Mask​
.setMask(MaskType type)
Defines which group of masks predefined in the product will be used by the SDK:
​
MaskType.DEFAULT, with the dotted pattern in the document format or face;
MaskType.DETAILED, which displays an illustration of the requested document - CNH or RG - along with the dotted mask (only in DocumentDetector);
MaskType.NONE, which removes the mask entirely.
No. The default masks are used.
DocumentDetector:
​DEFAULT and DETAILED;
PassiveFaceLiveness and FaceAuthenticator: DEFAULT​
Using the methods
DocumentDetector mDocumentDetector = new DocumentDetector.Builder(String mobileToken)
    .setLayout(R.layout.customLayout)
    .setStyle(R.style.customStyle)
    .setMask(MaskType.DETAILED)
    .build();
Different uses .setMask() method
DocumentDetector mDocumentDetector = new DocumentDetector.Builder(String mobileToken)
    // Using Customized Masks
    .setMask(R.drawable.customGreenMask, R.drawable.customWhiteMask, R.drawable.customRedMask)
    // Using masks already offered by the SDK
    .setMask(MaskType.DETAILED)
    .build();
Custom style creation
To create a new style, we recommend that you use the same template that we use, this way it will be easier to perform customizations.
Customization of masks
To customize the masks, first create a drawable resource in your project. You can customize whiteMask, greenMask, and redMask in any way you like. We have provided generic Document and Face masks that you can use for reference. See the setMask method definition and examples in DocumentDetector.Builder. And see also examples of custom mask integration.
Examples
We also have a repository on GitHub that contains a customization example, you can access it here.

Method	Description	Return	SDK
`takePhoto()`	Responsible for initiating image capture in MANUAL mode	Void	DocumentDetector, PassiveFaceLiveness
`close()`	Responsible for closing the SDK.	Void	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
`switchCamera()`	Responsible for reversing the camera.	Void	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator

Variable	Description	Type	SDK
`loadingStatus`	Indicates the 'loading' state	Boolean	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
`readyToCaptureStatus`	Indicates that the SDK is ready to capture, after performing all validations for sensors, framing, face, etc.	Boolean	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
`stepDoneSuccessfullyStatus`	Indicates that the capture step ended successfully	Boolean	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
`validationFailureStatus`	Indicates if there are any faulty sensor checks, quality, framing, face distance, etc.	Boolean	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
`validationFailureId`	Indicates what type of error has occurred. See the table below	ValidationFailure	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
`captureModeStatus`	Indicates the capture mode enabled. May vary between AUTOMATIC and MANUAL	CaptureMode	DocumentDetector, PassiveFaceLiveness
`maskStatus`	Indicates the status of the mask. Can range from NORMAL, SUCCESS to ERROR	Mask	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
`maskLayout`	Responsible for returning the Drawable Resource Id used to define the mask.	Integer	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
`previousStepName`	Name of the previous step that was performed. If not, the value will be null. Example: Back of ID.	String	DocumentDetector

Variable	Description	Type	SDK
`popUpVisibility`	Indicates the visibility of the step initialization popup	Boolean	DocumentDetector
`manualCaptureButtonVisibility`	Indicates visibility of the manual capture button	Boolean	DocumentDetector, PassiveFaceLiveness
`switchCameraButtonVisibility`	Indicates the visibility of the reverse camera button	Boolean	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
`statusVisibility`	Responsible for the visibility of the SDK status message.	Boolean	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
statusMessage	Returns the status message. Customize with MessageSettings	String	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
`cameraVisibility`	Responsible for camera visibility.	Boolean	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
`maskVisibility`	Indicates mask visibility.	Boolean	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
`switchButtonVisibility`	Responsible for the visibility of the camera flip button. This variable has been deprecated, we recommend using the switchCameraButtonVisibility variable.	Boolean	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
`serverRequesting`	Responsible for the visibility of the loading displayed by the SDK. This variable has been deprecated, we recommend using the loadingStatus variable.	Boolean	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
`buttonVisibility`	Sets the visibility of the manual capture button. This variable has been deprecated, use manualCaptureButtonVisibility.	Boolean	DocumentDetector, PassiveFaceLiveness

Error	Description	SDK
`SENSOR_LUMINOSITY_FAILURE`	Brightness sensor. The environment is too dark	DocumentDetector, PassiveFaceLiveness
`SENSOR_ORIENTATION_FAILURE`	Orientation sensor. Device not in correct position	DocumentDetector, PassiveFaceLiveness
`SENSOR_STABILITY_FAILURE`	Stability sensor. The device is in motion	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
`FRAMING_FAILURE`	Document or face-framing	DocumentDetector, PassiveFaceLiveness, FaceAuthenticator
`EYES_CLOSED_FAILURE`	A face with closed eyes was identified	PassiveFaceLiveness, FaceAuthenticator
`FACE_NOT_FOUND`	No face was found	PassiveFaceLiveness, FaceAuthenticator
`FACE_TOO_FAR`	Face too far away.	PassiveFaceLiveness, FaceAuthenticator
`FACE_TOO_CLOSE`	Very close face.	PassiveFaceLiveness, FaceAuthenticator
`ANGULATION_X_FAILURE`	Incorrect face angle on the X axis.	PassiveFaceLiveness
`ANGULATION_Y_FAILURE`	Incorrect face angle on the Y axis.	PassiveFaceLiveness
`ANGULATION_Z_FAILURE`	Incorrect face angle on the Z axis.	PassiveFaceLiveness
`MULTIPLE_FACES_FAILURE`	Multiple faces detected.	PassiveFaceLiveness, FaceAuthenticator
`QUALITY_FAILURE`	Quality of the document capture is too low.	DocumentDetector
`LIVENESS_FAILURE`	Error in the proof of life. It is a probable fraud attempt	PassiveFaceLiveness, FaceAuthenticator

Parameter	Required
`.setLayout(@LayoutRes Integer layoutId)` Replaces the default SDK layout. Create a file in your project's layout folder, copy one of these layout templates, according to the SDK you are integrating, DocumentDetector, PassiveFaceLiveness, FaceAuthenticator, and make the desired changes.	No. It follows the standard of each SDK: DocumentDetector PassiveFaceLiveness FaceAuthenticator
`.setStyle(@StyleRes int styleResourceId)` Replaces the SDK's default style. In your project's styles.xml file, copy this template and edit it.	No. This is the default, for all SDKs
`.setMask(@DrawableRes Integer greenMask, @DrawableRes Integer whiteMask, @DrawableRes Integer redMask)` Replaces the masks for capturing a document or face: SUCCESS, NORMAL, and FAIL, in that order. If you use this option, use masks with the same detection area of the document and face, as this region is very important for the algorithm to capture.	No. The defaults are found here: Mask for documents Face Mask
`.setMask(MaskType type)` Defines which group of masks predefined in the product will be used by the SDK: `MaskType.DEFAULT`, with the dotted pattern in the document format or face; `MaskType.DETAILED`, which displays an illustration of the requested document - CNH or RG - along with the dotted mask (only in DocumentDetector); `MaskType.NONE`, which removes the mask entirely.	No. The default masks are used. DocumentDetector: DEFAULT and DETAILED; PassiveFaceLiveness and FaceAuthenticator: DEFAULT

Last modified 11mo ago