Customization

This page presents a guide to layout customization in the iOS SDKs. The guide uses DocumentDetector as an example.

The Storyboard and xibs approach has been discontinued, but if you want to access the documentation, click here.

View Customization

1. Create a YourClass.swift class and extend it from DocumentOverlayView, PassiveOverlayView or FaceAuthOverlayView.

2. Override the init() method and call the constructor of the parent class:

class YourClass: DocumentOverlayView  {

    override init() {
        super.init()
    }
}r

3. In the DocumentOverlayView class (or the corresponding SDK), you can access:

• frame: CGRect, with the dimensions of the device screen;

• viewController: DocumentDetectorViewController?, for calling SDK methods.

4. Now build your elements using the ViewCode approach. To add an element to the view, use the self.addSubview(_ UIView) method:

class YourClass: DocumentOverlayView  {

    override init() {
        super.init()

        let example = UIView()
        example.backgroundColor = UIColor.white
        example.layer.cornerRadius = 8
        self.addSubview(self.example)
    }
}

5. To get UI updates, such as status changes, button visibility and masks, for example, override the methods below:

class YourClass: DocumentOverlayView {

    ...

    // MARK: - State methods

    public override func loading(status: Bool){
        //Indicates the "loading" status.
        // The 'status' variable will be 'true' according to the SDK opening, image capture, requests to the backend...
    }

    public override func readyToCapture(status: Bool){
        // indicates that the SDK is ready to capture, after performing all validations of sensors, framing, face, etc.    }

    public override func stepDoneSuccessfully(status: Bool){
        //Indicates that the capture step ended successfully
    }

    public override func validationFailure(status: Bool, id: ValidationFailure?){
        // The 'status' variable indicates whether there are any failures in the sensor checks, quality, framing, face distance, etc.
        // Most validation failures generate the "error mask" status
        // The variable 'id' indicates what type of error occurred. See the table below
    }

    public override func captureMode(status: CaptureMode){
        // Indicates the capture mode enabled. May vary between AUTOMATIC and MANUAL
    }

    public override func mask(status: Mask, visibility: Bool){
        // The variable 'visibility' indicates the visibility of the mask or feedback area
        if(visibility){
            switch type {
            case .normal:
                // Display the normal state mask               
                break
            case .success:
                // Present the mask of success
                break
            case .error:
                // Display the error mask
                break
            default:
                // Display the normal state mask
                break;
            }
        }
    }

    // MARK: - Visibility methods

    // Only available for DocumentDetector
    public override func popup(visibility: Bool){
        // Indicates the visibility of the step initialization popup
    }

    public override func manualCaptureButton(visibility: Bool){
        // Indicates visibility of the manual capture button
    }

    // Only available for DocumentDetector and PassiveFaceLiveness
    public override func preview(visibility: Bool){
        // Indicates the visibility of the Preview (post-capture) screen
    }

    public override func status(message: String, visibility: Bool) {
        // Use to indicate the message that should be displayed according to the states of the SDK
    }

    public override func currentStep(name: String){
        // Indicates the name of the current step
    }

    // MARK: - Deprecated methods. We do not recommend using them because in future versions they will be removed

    public override func show(loading show: Bool) {
        // Use to indicate "loading" state
    }
    
    public override func show(message text: String) {
        // Present the messages to the user
    }

    open func show(stepName text: String) {
        // Indicates the name of the current step
    }
    
    public override func show(mask type: Mask) {
       switch type {
            case .normal:
                // Display the normal state mask               
                break
            case .success:
                // Present the mask of success
                break
            case .error:
                // Display the error mask
                break
            default:
                // Display the normal state mask
                break;
        }
    }

    public override func show(manualCaptureButton hidden: Bool) {
        // Show or disable the manual capture button
    }

    public override func setCurrentAction(text: String, checked: Bool){
        // Present the current step with the `text' attribute
    }

    public override func setLastAction(text: String){
        // The `text` attribute returns the last step taken. It can be used to display the capture steps already performed.
    }
}

6. For implementation of the close button, the cancelButtonClick method must be called. This method triggers the documentDetectorControllerDidCancel delegate and cancels the capture:

@objc func closeButtonClick(sender: UIButton!) {
        self.viewController.cancelButtonClick()
    }

7. For the manual capture button, the clickButtonManualCapture method should be called:

@objc func manualButtonClick(sender: UIButton!) {
        self.viewController?.clickButtonManualCapture()
    }

8. Finally, in DocumentDetector.CafBuilder use the method, .setOverlay(overlay: DocumentOverlayView).

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 is not in the 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
FACE_NOT_FOUND	No face was found	PassiveFaceLiveness, FaceAuthenticator
FACE_TOO_FAR	Very distant face.	PassiveFaceLiveness, FaceAuthenticator
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