Face Login

Face Login

Prerequisites

  • User has to be an approved customer by doing a complete onboarding flow.

Initialize IncdOnboarding SDK

Add the following line of code to your AppDelegate class:

IncdOnboardingManager.shared.initIncdOnboarding(url: url, apiKey: apiKey)

url and apiKey will be provided to you by Incode.
If you're running the app on a simulator, please set the testMode parameter to true.

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. In case system detects a couple of similar faces it will peform step-up authenication, so that user can confirm the identity by entering requested code.

To execute 1:N Face Login call startFaceLogin method:

IncdOnboardingManager.shared.presentingViewController = self
IncdOnboardingManager.shared.startFaceLogin() { result in
          guard let loginResult = result.faceLoginResult else {
            // Some error occured
            print(result.error)
            return
          }
          
          if loginResult.success == true {
            // Face auth successful
            let customerUUID = loginResult.customerUUID
            let token = loginResult.token
            let interviewId = loginResult.interviewId
          } else {
            if result.spoofAttempt == true {
              // Liveness failed
            } else {
              // User's face not found
            }
          }
        }

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.

IncdOnboardingManager.shared.presentingViewController = self
IncdOnboardingManager.shared.startFaceLogin(customerUUID: "YOUR_CUSTOMER_ID") { result in
          guard let loginResult = result.faceLoginResult else {
            // Some error occured
            print(result.error)
            return
          }
          
          if loginResult.success == true {
            // Face auth successful
            let customerUUID = loginResult.customerUUID
            let token = loginResult.token
            let interviewId = loginResult.interviewId
          } else {
            if result.spoofAttempt == true {
              // Liveness failed
            } else {
              // User's face not found
            }
          }
        }

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 oterhwise.
    • 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.
  • spoofAttempt - Specifies if it was a spoof attempt or not
  • image - Selfie image taken during Selfie scan step
  • error - SelfieScanError that describes the error that happened during face login

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 check please specify FaceAuthMode.hybrid via faceAuthMode param of the startFaceLogin method:

IncdOnboardingManager.shared.presentingViewController = self
IncdOnboardingManager.shared.startFaceLogin(faceAuthMode: .hybrid) { result in
          ...
        }

To switch to both on-device liveness check and face match please specify FaceAuthMode.local via faceAuthMode param of the startFaceLogin method:

IncdOnboardingManager.shared.presentingViewController = self
IncdOnboardingManager.shared.startFaceLogin(faceAuthMode: .local) { result in
          ...
        }

NOTE: FaceAuthMode.hybrid and FaceAuthMode.local require specific Onboarding SDK frameworks with FaceAuth models included. If using cocoapods specify l variant, ie. 5.5.0-d-l.

Other parameters:

  • showTutorials: Show tutorials how to capture selfie before the actual scan. true by default.
  • faceAuthModeFallback - Specify true if you would want to do a FaceAuthMode.server face login in case FaceAuthMode.local couldn't be performed due to missing face template on the device. This is applied only to 1:1 Face login.
  • lensesCheck: Set to false if you would like to disable lenses detection during selfie scan. true by default.
  • faceMaskCheck: Specify true to enable face mask check detection during face capture. false by default.
  • brightnessThreshold: 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.
  • logAuthenticationEnabled: Specify false to disable sending liveness statistics after a login attempt. true by default.
  • customLogo: Specify a custom logo to display during face capture step. If not specified use default logo.

Manipulating locally stored identities

To be able to authenticate multiple users using 1:N and FaceAuhtMode.local mode you'll need to add these users to the local database. This section will describe which methods you can use to perform CRUD operations with locally stored identities.

Add Face

To add a single identity to the local dabtase, use addFace method and provide a FaceInfo object, that contains:

  • faceTemplate: String -> biometric representation of a user's face
  • customerUUID: String -> unique customer identifer in Incode's database
  • templateId: String -> unique identifier of a biometric representation of a user's face in Incode's database
let face = FaceInfo(faceTemplate: template,
                    customerUUID: uuid,
                    templateId: templateId)
IncdOnboardingManager.shared.addFace(face)

Remove Face

To remove a single identity from the local database use removeFace method and provide a customerUUID:

IncdOnboardingManager.shared.removeFace(customerUUID: customerUUID)

Get faces

To fetch all currently stored identities use getFaces method.

  var identities: [FaceInfo] = IncdOnboardingManager.shared.getFaces()

Set multiple faces

To add multiple identities at once you can use setFaces method and provide a list of FaceInfo objects, but keep in mind it will firstly wipe out all currently stored identities.

IncdOnboardingManager.shared.setFaces(faceInfoList)

Clear face database

To clear local database use setFaces method and provide empty FaceInfo list of objects.

IncdOnboardingManager.shared.setFaces([])