Enrol and Export

4Finger ID can be configured to both enroll a user into the VeridiumID service and export the same enrollment data in the chosen export format. This allows user onboarding with an existing fingerprint database.

This document shows how 4Finger ID enroll and export functionality can be used through Veridium SDK on Android and iOS platforms.

(Refer to Architecture for biometric library registration and configuration in more detail).

iOS

Strong Authenticators

Register the Veridium 4F Exporter.
In order to use export and enroll functionality, the Veridium 4F exporter should be registered like 4F enroller and authenticator. The following code snippet shows how is it done:
CODE
```
...
veridiumSDK.register4FUIAuthenticator()
veridiumSDK.register4FUIEnroller()
...
veridiumSDK.register4FUIExporter()
```

Prepare the configuration for enrollment.

The enrollment flow starts with the VeridiumMobileSDK.shared().enroll(config:) SDK API call. In order to include enroll and export functionality, the config parameter should be initialized with a dictionary of biometric engine name - VeridiumBiometricExportConfig key pairs. The following code shows how this can be done for the 4Finger ID:

CODE

let fourfExportConfig = VeridiumFourFCaptureConfig()
  // Please note that both do_export and do_enroll should be set to true
  config.do_enroll = true
  config.do_export = true
  // Desired export template data format should be provided
  config.exportFormat = .FORMAT_JSON
  // Other configurations
  ...
  
// The dictionary with biometric engine name - VeridiumBioExportConfig pairs
let exportConfigDict = [kVeridiumBiometricEngineName4F: fourfExportConfig]

// Initialise the VIDEnrollmentConfig instance with exportConfigDict
let enrollmentConfig = VIDEnrollmentConfig(userEnrollmentToken: nil, 
                                              exportConfigDict: exportConfigDict)

// Start the enrollment with API call                                              
VIDMobileSDK.shared().enroll(config: enrollmentConfig)

Get exported biometric data through enrollment delegate.

If the VIDEnrollmentConfig instance is provided with the export config dictionary, the SDK performs the enrollment with enroll and export functionality, and the resulting template data in desired export format is provided through the VIDEnrollDelegate method as Data

The following code shows how the export template data is provided for 4Finger ID:

CODE

extension SomeClass: VIDEnrollDelegate {

  // Enrollment is completed successfully
  func didFinishEnrollment(response: VIDEnrollResponse) {
      // VIDEnrollResponse includes exportDataDict field, 
      // which has biometric engine name - biometric template data key-value pairs 
      if let fourFExportTemplate: Data = response.exportDataDict?[kVeridiumBiometricEngineName4F] {
          // fourFExportTemplate can be used according to the export format 
          // defined in the export configuration   
      }
      ...
  }

  ...

}

Kiosk Mode

Register the Veridium 4F exporter.

The Veridium Kiosk SDK also supports the enroll and export functionality. In order to use the functionality, same as above, the Veridium 4F exporter should be registered. This can be achieved by registering the exporter in theVIDBioLibConfiguration implementation. The following code shows how is it done:

CODE

class FourFBiolibConfiguration: VIDBioLibConfiguration {
  ...
  
  func registerBiometricEnrollerAndAuthenticator(using veridiumSDK: VeridiumSDK) {
      veridiumSDK.register4FUIAuthenticator()
      veridiumSDK.register4FUIEnroller()
      // register the exporter here with the enroller and the authenticator
      veridiumSDK.register4FUIExporter()
  }

  ... 
}

Prepare the configuration for enrollment.

The enrollment flow starts with the registerAccount(options:callback:) SDK API method call. In order to include enroll and export functionality, the options parameter, which is a VIDRegisterAccountOptions instance, should be initialized accordingly. The VIDRegisterAccountOptions should be initialized with a biometric engine name - biometric export config dictionary. The following code shows how is it done:

CODE

let fourfExportConfig = VeridiumFourFCaptureConfig()
  // Please note that both do_export and do_enroll should be set to true
  config.do_enroll = true
  config.do_export = true
  // Desired export template data format should be provided
  config.exportFormat = .FORMAT_JSON
  // Other configurations
  ...
  
// The dictionary with biometric engine name - VeridiumBioExportConfig pairs
let exportConfigDict = [kVeridiumBiometricEngineName4F: fourfExportConfig]

// Initialise the VIDRegisterAccountOptions instance with exportConfigDict
let registrationOptions = VIDRegisterAccountOptions(loginData: loginData,
            memberExternalId: VeridiumConstants.memberExternalId,
            registrationMode: "KIOSK",
            exportConfigDict: exportConfigDict)

// Start the enrollment with the SDK API call        
veridiumKioskSDKInstance.registerAccount(options: registrationOptions) { result, error in
    ...
}

Get exported biometric data through callback.

The export biometric template data is provided through the callback parameter of the registerAccount(options:callback:) SDK API method. The callback provides VIDEnrolmentResult instance, which includes the biometric template data if the enrollment is successful. The following code shows how the biometric template data can be retrieved:

CODE

veridiumKioskSDKInstance.registerAccount(options: registrationOptions) { result, error in
    ...
    switch result.state {
        case .ENROLED:
        // VIDEnrolmentResult includes the exportTemplateData field, 
        // which has biometric engine name - biometric template data key-value pairs
        if let fourFExportTemplate: Data = result.exportTemplateData[kBiometricEngineName4F] {
            // fourFExportTemplate can be used according to the export format 
            // defined in the export configuration   
        }
        ...
    }
}

Android

Strong Authenticators

The enroll export functionality was added on top of the existing enrollment, but the 4F configuration is also taken into consideration. In order to request an enroll export, in the enrollment request should be specified the output location (Uri) where the export capture will be written by the SDK. Also it’s mandatory that all the configuration related to the capture to be specified before the request is executed.

CODE

int REQUEST_CODE_ENROLL = 1
Uri exportUri = getExportUri(".json"); // The URI where the export 4F will be written.

private void enroll() {
  VeridiumIdRegisterRequest.Builder requestBuilder = new VeridiumIdRegisterRequest.Builder()
          .withBiometricExport(FourFInterface.UID, MainActivity.sFourFExportUri);
          .build();
  setupFourFExportConfiguration()
  VeridiumIdPendingIntent pendingIntent = VeridiumMobileSDK.getInstance().enroll(requestBuilder.build());
  if (pendingIntent.hasPendingIntent()) {
      try {
          pendingIntent.launchPendingIntent(this, REQUEST_CODE_ENROLL);
      } catch (IntentSender.SendIntentException e) {
          e.printStackTrace();
      }
  }
}

// Configuration example 
private void setupFourFExportConfiguration(){
    ExportConfig.setFormat(IBiometricFormats.TemplateFormat.FORMAT_JSON);
    ExportConfig.setPack_wsq(true);
    ExportConfig.setWSQCompressRatio(ExportConfig.WSQCompressRatio.COMPRESS_2to1);
}

private Uri getExportUri(String ext) throws IOException {
    File directory = getContext().getCacheDir();
    File file = File.createTempFile(
            "4F_export_",  /* prefix */
            ext,         /* suffix */
            directory      /* directory */
    );
  
    return Uri.fromFile(file);
}

The result is handled similar with a normal enrollment, the only side-effect is that the export capture will be available in the Uri submitted at request time.

CODE

@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (resultCode == RESULT_CANCELED)
        return;

    if (requestCode == REQUEST_CODE_ENROLL) {
        VeridiumIdErrorResponse errorResponse = data.getParcelableExtra(VeridiumMobileSDK.VERIDIUMID_KEY_ERROR_EXTRA);
        if(errorResponse == null){
            // The export capture was written in the exportUri according to the 4F configuration
            
        } else {
          // Handle enrollment error.
        }
}

Kiosk Mode

The enroll export functionality was added on top of the existing enrollment, but the 4F configuration is also taken into consideration. In order to request an enroll export, in the enrollment request should be specified the output location (Uri) where the export capture will be written by the SDK. Also it’s mandatory that all the configuration related to the capture to be specified before the request is executed.

CODE

int REQUEST_CODE_ENROLL = 1Uri exportUri = getExportUri(".json"); // The URI where the export 4F will be written.
private void enroll() { AccountRegistrationRequest.Builder registrationRequestBuilder = new AccountRegistrationRequest.Builder(MEMBER_EXRERNAL_ID, jsonObject.toString())          .setRegistrationMode(REGISTRATION_MODE)          .withBiometric(FourFInterface.UID);          .withTemplateExport(FourFInterface.UID, mExportUri);                   setupFourFExportConfiguration()  mKioskSdk.register(registrationRequestBuilder.build())        .continueWith(task -> {              if (task.isCancelled()) {                      Toast.makeText(this, "Registration cancelled!", Toast.LENGTH_SHORT).show();                  } else if (task.isSuccessful()) {                      VeridiumPendingIntent pendingIntent = task.getResult();                      if (pendingIntent.hasPendingIntent()) {                          pendingIntent.launchPendingIntent(MainActivity.this, REQUEST_CODE_ENROLL);                      }                  } else {                     // Account registration task failed.                  }                  return null;              }, Task.MAIN_THREAD_EXECUTOR)        });
// Configuration eint REQUEST_CODE_ENROLL = 1
Uri exportUri = getExportUri(".json"); // The URI where the export 4F will be written.

private void enroll() {
 AccountRegistrationRequest.Builder registrationRequestBuilder = new AccountRegistrationRequest.Builder(MEMBER_EXRERNAL_ID, jsonObject.toString())
          .setRegistrationMode(REGISTRATION_MODE)
          .withBiometric(FourFInterface.UID);
          .withTemplateExport(FourFInterface.UID, mExportUri);                 
  setupFourFExportConfiguration()
  mKioskSdk.register(registrationRequestBuilder.build())
        .continueWith(task -> {
              if (task.isCancelled()) {
                      Toast.makeText(this, "Registration cancelled!", Toast.LENGTH_SHORT).show();
                  } else if (task.isSuccessful()) {
                      VeridiumPendingIntent pendingIntent = task.getResult();
                      if (pendingIntent.hasPendingIntent()) {
                          pendingIntent.launchPendingIntent(MainActivity.this, REQUEST_CODE_ENROLL);
                      }
                  } else {
                     // Account registration task failed.
                  }
                  return null;
              }, Task.MAIN_THREAD_EXECUTOR)
        });

// Configuration example 
private void setupFourFExportConfiguration(){
    ExportConfig.setFormat(IBiometricFormats.TemplateFormat.FORMAT_JSON);
    ExportConfig.setPack_wsq(true);
    ExportConfig.setWSQCompressRatio(ExportConfig.WSQCompressRatio.COMPRESS_2to1);
}

private Uri getExportUri(String ext) throws IOException {
    File directory = getContext().getCacheDir();
    File file = File.createTempFile(
            "4F_export_",  /* prefix */
            ext,         /* suffix */
            directory      /* directory */
    );
  
    return Uri.fromFile(file);
}xample private void setupFourFExportConfiguration(){    ExportConfig.setFormat(IBiometricFormats.TemplateFormat.FORMAT_JSON);    ExportConfig.setPack_wsq(true);    ExportConfig.setWSQCompressRatio(ExportConfig.WSQCompressRatio.COMPRESS_2to1);}
private Uri getExportUri(String ext) throws IOException {    File directory = getContext().getCacheDir();    File file = File.createTempFile(            "4F_export_",  /* prefix */            ext,         /* suffix */            directory      /* directory */    );      return Uri.fromFile(file);}

The result is handled similar with a normal enrollment, the only side-effect is that the export capture will be available in the Uri submitted at request time.

CODE

@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (resultCode == RESULT_CANCELED)
        return;

    if (requestCode == REQUEST_CODE_ENROLL) {
        KioskErrorResponse response = data.getParcelableExtra(VeridiumKioskSDK.KIOSK_KEY_ERROR_EXTRA);
        if(errorResponse == null){
            // The export capture was written in the exportUri according to the 4F configuration
            
        } else {
          // Handle enrollment error.
        }
}