2️⃣ Enrollment

Enrollment is the process of registering a new user by connecting their facial biometrics to a Keyless account. During this process, a full and unobstructed view of the user's face is required.

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

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

During enrolment you can specify a custom secret to be saved and encrypted along with the user's biometric data using savingSecret method. The custom secret can be anything you can save as an ASCII string, such as a secret that you have provided to the app from the backend, the seed of an OTP protocol, or anything else.

Backup data

Keyless can generate backup data that you can use to recover an account.

To create the backup data use the retrievingBackup method. Once the enrollment succeeds, copy the backup data from the EnrollmentSuccess result, and store it securely.

To recover an account, use withBackup passing as parameter the backup data you stored previously.

Liveness Settings

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

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

More details on liveness levels in the SDK Reference.

Operation info

withOperationInfo specifies a customizable unique operation identifier and associated payload stored on the Keyless backend if the enrollment succeeds. Use this to add an extra level of confirmation in your operations.

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

Enrollment Delay

Use withDelay to specify the delay (in seconds) between when the camera preview appears, and when the liveness processing starts.

Enrollment Selfie

Using withEnrollmentSelfie you can retrieve the image that Keyless uses to computes the facial biometrics of the user. The image can be found in the EnrollmentSuccess result.