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.Builder 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

Last updated

Logo

2023 © Caf. - All rights reserved