Enrollment

Enrollment creates a Keyless account. You can think of "enrollment" as a "register/signup" process. During the enrollment Keyless ties the user's face biometrics to the Keyless account.

For the enrolment, a full face image is required and the process cannot be completed if any occlusion is present, e.g. a face mask.

Android

val configuration = EnrollmentConfiguration.builder.build()

Keyless.enroll(
  enrollmentConfiguration = configuration,
  onCompletion = { result ->
    when (result) {
      is Keyless.KeylessResult.Success -> Log.d("KeylessSDK ", "Enroll success - userId ${result.value.keylessId}")
      is Keyless.KeylessResult.Failure -> Log.d("KeylessSDK ", "Enroll failure - error code ${result.error.code}")
    }
  }
)   

iOS

let configuration = Keyless.EnrollmentConfiguration.builder.build()
            
Keyless.enroll(
  enrollmentConfiguration: configuration,
  onCompletion: { result in
    switch result {
    case .success(let enrollmentSuccess):
        print("Enrollment finished successfully. UserID: \(enrollmentSuccess.keylessId)")
    case .failure(let error):
        print("Enrollment finished with error: \(error.message)
    }
  })

Enrollment builder methods

You can customize the enrollment with optional methods from the EnrollmentConfiguration builder. The full EnrollmentConfiguration is available below:

Android

interface EnrollmentConfigurationBuilder {

    fun retrievingBackup(): EnrollmentConfigurationBuilder
    
    fun savingSecret(customSecret: String): EnrollmentConfigurationBuilder

    fun withBackup(backupKey: ByteArray, backupData: ByteArray): EnrollmentConfigurationBuilder
    
    fun withDelay(cameraDelaySeconds: Int): EnrollmentConfigurationBuilder
    
    fun withEnrollmentSelfie(): EnrollmentConfigurationBuilder
    
    fun withLivenessSettings(
        livenessConfiguration: LivenessSettings.LivenessConfiguration,
        livenessTimeout: Int
    ): EnrollmentConfigurationBuilder
    
    fun withOperationInfo(
        operationId: String,
        payload: String? = null,
        externalUserId: String? = null
    ): EnrollmentConfigurationBuilder
    
    fun withPin(pin: String): EnrollmentConfigurationBuilder
    
    fun withTemporaryState(temporaryState: String): EnrollmentConfigurationBuilder
    
    fun build(): EnrollmentConfiguration
}

iOS

public protocol EnrollmentConfigurationBuilder {
    
    func retrievingBackup() -> EnrollmentConfigurationBuilder
    
    func savingSecret(_ customSecret: String) -> EnrollmentConfigurationBuilder

    func withBackup(_ backup: Keyless.Backup) -> EnrollmentConfigurationBuilder 
    
    func withDelay(seconds: Int) -> EnrollmentConfigurationBuilder
    
    func withEnrollmentSelfie() -> EnrollmentConfigurationBuilder
    
    func withLivenessSettings(
        livenessConfiguration: Keyless.LivenessConfiguration,
        livenessTimeout: Int
    ) -> EnrollmentConfigurationBuilder
    
    func withOperationInfo(
        id: String,
        payload: String?,
        externalUserId: String?
    ) -> EnrollmentConfigurationBuilder
    
    func withPin(_ pin: String) -> EnrollmentConfigurationBuilder
    
    func withTemporaryState(_ temporaryState: String) -> EnrollmentConfigurationBuilder
    
    func build() -> Keyless.EnrollmentConfiguration
}

Enrollment success result

Depending on the builder methods you enable, Keyless will populate the corresponding fields in the EnrollmentSuccess result reported below. Not all builder methods produce a result as output that is why you have less fields in output than the number of methods of the builder.

Android

data class EnrollmentSuccess(
    val backup: KeylessBackup? = null,
    val customSecret: String = "",
    val enrollmentSelfie: Bitmap? = null,
    val keylessId: String,
) : KeylessSdkSuccess()

iOS

public struct EnrollmentSuccess {
        public let backup: Keyless.Backup?
        public let customSecret: String?
        public let enrollmentSelfie: CGImage?
        public let keylessId: String?
}

Custom secret

it is possible to protect with the user's face biometrics a "secret" that you provide as input.

Depending on your application logic, you can choose to use different secrets.

Your custom secret could be a secret that you have provided to the app from the backend, the seed of an OTP protocol, or anything else. If you only need to know just the result of the authentication (success/failed), you can provide any constant value as token.

Keyless accepts only ASCII strings as custom token.

Using the savingSecret method you can specify an ASCII string to store securely with Keyless. You can retrieve the secret later on after a successful authentication.

Backup Retrieval and Recovery

Keyless can generate backup data useful to recover an account.

You are responsible to store the backup data securely.

To retrieve the backup data use retrievingBackup method. Once the enrollment succeeds you can read the backup data in the EnrollmentSuccess result.

To recover and account you can enroll with backup data that you retrieved and stored in the past. To recover an account use withBackup passing as parameter the backup data.

Liveness Settings

Using withLivenessSettings you can specify the liveness security level choosing the options from LivenessConfiguration.

You can also specify a timeout (in seconds) to cancel the enrollment if the liveness takes longer than the timeout.

Operation info

withOperationInfo specifies an operation identifier and payload stored on the Keyless backend if the enrollment succeeds.

Each operation id must be unique, you will get an error if you re-use the same operation id.

Details on how to query our backend for stored operations are available on Operations API.

Enrollment Delay

Using withDelay you can specify the delay (in seconds) to delay the liveness start. The camera preview appears but the liveness processing waits for the specified delay before starting.

Enrollment Selfie

Only available to some customers. If you are not eligible you will get an error. Using withEnrollmentSelfie you can retrieve the image from which Keyless computes the biometrics of the user. The image can be found in the EnrollmentSuccess result.

Temporary State

If you enrolled users from a different source than the mobile SDK (e.g. Keyless Agent), you need to sync the mobile SDK with the state returned by the Keyless Agent.

To synch the mobile SDK enroll providing the "temporary state" or "shared state". Specify withTemporaryState in the EnrollemntConfiguration builder.

The UI is the UI for the authentication even if you called an EnollmentCondifuration. This is expected since from the user perspective the enrollment was already performed previously.