Skip to main content

Face Login

This guide explains how to use the face login feature in Welcome SDK.

Prerequisites​

User has to be an approved customer by having completed the onboarding flow. Check the image below for more information.

Onboarding and Login

Initialize Welcome SDK as described here​

1:N Face Login - Identify a user​

1:N Face login is suitable if you would like to identify a user by doing a face scan. This will do a face match comparison across your whole user database and check if the face corresponds to any of the approved users.

To execute 1:N Face Login call startFaceLogin method:​

IncodeWelcome.getInstance().startFaceLogin(this, new SelfieScan.Builder().build(), new SelfieScanListener() {
            @Override
            public void onSelfieScanCompleted(SelfieScanResult selfieScanResult) {
                if (selfieScanResult.status == SelfieScanResult.STATUS_OK) {
                    if (selfieScanResult.faceLoginResult.success == true) {
                        String customerUUID = selfieScanResult.faceLoginResult.customerUUID;
                        String token = selfieScanResult.faceLoginResult.token;
                        String interviewId = selfieScanResult.faceLoginResult.interviewId;
                    } else {
                        if (selfieScanResult.isSpoofAttempt == true) {
                            // Liveness failed
                        } else {
                            // User's face not found
                        }
                    }
                } else {
                    // Some of the preconditions for checking liveness failed, check selfieScanResult.status for specific info
                }
            }

            @Override
            public void onError(Throwable error) {
                // Some error occurred
            }

            @Override
            public void onUserCancelled() {
                // User canceled login
            }
        });
});

1:1 Face Login - Verify Face for a specific user​

1:1 Face Login is suitable if you want do a Face authentication for a specific user that is already pre-authorized, meaning you already have his customer UUID and want to only know if this exact person is trying to authenticate.

To execute 1:1 Face Login call startFaceLogin method:​

IncodeWelcome.getInstance().startFaceLogin(this, new SelfieScan.Builder().setCustomerUUID("YOUR_CUSTOMER_ID").build(), new SelfieScanListener() {
            @Override
            public void onSelfieScanCompleted(SelfieScanResult selfieScanResult) {
                if (selfieScanResult.status == SelfieScanResult.STATUS_OK) {
                    if (selfieScanResult.faceLoginResult.success == true) {
                        String customerUUID = selfieScanResult.faceLoginResult.customerUUID;
                        String token = selfieScanResult.faceLoginResult.token;
                        String interviewId = selfieScanResult.faceLoginResult.interviewId;
                    } else {
                        if (selfieScanResult.isSpoofAttempt == true) {
                            // Liveness failed
                        } else {
                            // User's face is not similar to previously enrolled face
                        }
                    }
                } else {
                    // Some of the preconditions for checking liveness failed, check selfieScanResult.status for specific info
                }
            }

            @Override
            public void onError(Throwable error) {
                // Some error occurred
            }

            @Override
            public void onUserCancelled() {
                // User canceled login
            }
        });
});

Face Login result​

Resulting SelfieScanResult object will have:

  • faceLoginResult - FaceLoginResult object that contains:
    • success - True if face login was successful, false otherwise
    • customerUUID - Customer UUID of the matched user, nil otherwise
    • token - Customer token of the matched user, nil otherwise
    • interviewId - Session interviewId from which the user got approved
    • interviewToken - Session interviewToken which was used during user approval
    • transactionId - Transaction ID of the face login attempt
  • isSpoofAttempt - Specifies if it was a spoof attempt or not
  • croppedSelfieImgPath - Cropped selfie image location taken during Selfie scan step
  • fullFrameSelfieImgPath - Full frame selfie image location taken during Selfie scan step
  • selfieEncryptedBase64 - Encrypted Base64-encoded selfie image
  • selfieBase64 - Base64-encoded selfie image
  • isFaceMatched - True if face login was successful, false otherwise. Same information as faceLoginResult.success
  • hasFaceMask - True if face mask is detected, false otherwise. Null in check wasn't performed
  • error - Throwable that describes the error that happened during face login
  • resultCode - Result code common to all IncodeWelcome results

Login parametrization​

By default Face Login will do a liveness check and face match on the server, and we highly suggest switching to on-device liveness check and face match in order to improve the speed of Face Login and reduce network traffic, which is particulary important for devices that can have unstable network connection.

To switch to on-device liveness:​

  1. In your module-level app/build.gradle, add additional Incode dependency:
dependencies {
    ...
    implementation 'com.incode.sdk:model-liveness-detection:2.0.0'
}
  1. Specify FaceAuthMode.HYBRID when creating SelfieScan module
SelfieScan selfieScan = new SelfieScan.Builder()
        .setFaceAuthMode(SelfieScan.FaceAuthMode.HYBRID)
        .build();

To switch to on-device liveness and on-device face recognition include:​

  1. In your module-level app/build.gradle, add additional Incode dependency:
dependencies {
    ...
    implementation 'com.incode.sdk:model-liveness-detection:2.0.0'
    implementation 'com.incode.sdk:model-face-recognition:2.0.0'
}
  1. Specify FaceAuthMode.LOCAL when creating SelfieScan module
SelfieScan selfieScan = new SelfieScan.Builder()
        .setFaceAuthMode(SelfieScan.FaceAuthMode.LOCAL)
        .build();

Note: SelfieScan.FaceAuthMode.LOCAL can work only in 1:1 mode and if user's face template is already saved locally in the device. Template gets saved during successful onboarding or by using allowFaceAuthModeFallback parameter (please check explanation below).

Other parameters to consider:

  • setCustomerUUID: ID that uniquely identifies the pre-authorized user who is performing face login. When set, 1:1 login is performed. When this value is null, 1:N login is performed.
  • setShowTutorials: Show tutorials how to capture selfie before the actual scan. true by default.
  • setWaitForTutorials: Hide the continue button in the tutorial screen while tutorial animation is playing, in order to make sure user has seen the video before continuing. true by default.
  • setAllowFaceAuthModeFallback - Specify true if you would want to do a SelfieScan.FaceAuthMode.SERVER face login in case SelfieScan.FaceAuthMode.LOCAL couldn't be performed due to missing face template on the device. This is applied only to 1:1 Face login.
  • setLensesCheckEnabled: Set to false if you would like to disable lenses detection during selfie scan. true by default.
  • setMaskCheckEnabled: Specify true to enable face mask check detection during face capture. false by default. Face Mask Check is performed on the server, unless local mask detection dependency is included in module-level app/build.gradle.
  • setBrightnessThreshold: Adjust minimum requirements for a well lit face during capture. Increasing the value will be more restrictive and require better lighting conditions, decreasing the value will lossen requirements and allow capturing while being in a darker environment. Set 0 to ignore this setting. 50 by default.
  • setCameraFacing: Sets the direction that the camera faces. It can be CameraFacing.FRONT or CameraFacing.BACK. CameraFacing.FRONT by default.
  • setLogAuthenticationEnabled: Specify false if you e.g. want to make sure that no network calls are being performed in SelfieScan.FaceAuthMode.LOCAL mode. Note that the authentication attempts won't be visible in the dashboard. true by default.
  • setAssistedOnboardingEnabled: Enables assisted onboarding (back-camera-only onboarding). This is equivalent to setCameraFacing(CameraFacing.BACK).

Kiosk Login​

Kiosk Login is a special face login mode for shared devices with large screens, e.g. tablets. This mode is optimized for a faster login experience. The main factors which accelerate this are:

  1. Liveness check is disabled.
  2. Face recognition is done on the server, but without the need to upload a photo. The face template is generated on the device and sent to the server. The server does the match based on the template. The template is significantly smaller than the photo, speeding up the network communication.
  3. Kiosk Login has a special UX with a full screen camera and relaxed face position constrains.

In order to use Kiosk Login, specify FaceAuthMode.FR_ONLY when creating the SelfieScan module:

SelfieScan selfieScan = new SelfieScan.Builder()
        .setFaceAuthMode(SelfieScan.FaceAuthMode.FR_ONLY)
        .build();