Description

Face Authentication is an Incode Module that asks a user to take a selfie. The selfie is then compared to a previously onboarded user to verify the user is who they claim to be.

Prerequisite

You must configure Face Authentication module on the Incode Dashboard before you can use it in your identity verification process.

Integration options

Low-code integration

Using startFlow or startWorkflow methods

Full SDK integration

Face Authentication can be setup via SDK and used in startOnboarding or startOnboardingSection methods.

All integrations start with initialization of the SDK, as shown in the following image.

public static void IncodeSDKInitialize(Application app) {
  try {

    new IncodeWelcome.Builder(app, Constants.API_URL, Constants.API_KEY)
      .setLoggingEnabled(true)
      .build();

    incodeSDKInitialized = true;
  } catch (Exception exception) {
    incodeSDKInitialized = false;
  }
}

private void setIncodeCommonConfig() {
  CommonConfig commonConfig = new com.incode.welcome_sdk.CommonConfig.Builder()
    .setShowExitConfirmation(true)
    .setShowCloseButton(true)
    .build();

  IncodeWelcome.getInstance().setCommonConfig(commonConfig);
}

func incodeSDKInitialize(api_url: String, api_key: String) {
  IncdOnboardingManager.shared.initIncdOnboarding(url: api_url,
                                                  apiKey: api_key,
                                                  loggingEnabled: true,
                                                  testMode: testMode) { (success, error) in
        print("IncdOnboarding SDK initialization, success: \(success == true), error: \(error?.description ?? "nil")")
        self.dispatchGroup.leave()
    }
}

func setIncodeCommonConfig() {
  IncdOnboardingManager.shared.allowUserToCancel = true
  IncdOnboardingManager.shared.idBackShownAsFrontCheck = true
  IncdOnboardingManager.shared.idFrontShownAsBackCheck = true
}

const IncodeSDKInitialize = (API_URL, API_KEY) => {
    IncodeSdk.initialize({
      testMode: false,
      apiConfig: {
        url: API_URL,
        key: API_KEY,
      }
    })
      .then((_) => {
        console.log('Incode SDK init success')
      })
      .catch((e) => {
        console.error('Incode SDK failed init', e);
      });
  };

void IncodeSDKInitialize(API_URL,API_KEY) {
	IncodeOnboardingSdk.init(
      apiKey: API_KEY,
      apiUrl: API_URL,
      onError: (String error) {
        print('Incode SDK init failed: $error');
      },
      onSuccess: () {
        print('Incode SDK init success');
      },
    );
}

cordova.exec(function(param) {
         console.log("Success: "+param);
        // start the incode session here
         }, function(err) {
          console.log("Error: "+ err);
           // handle the error by showing some UI or alert.
       }, "Cplugin", "initializeSDK", [apiKey,apiUrl,loggingEnabled,testMode]);

If you configure a 1:1 Face Authentication method on the Dashboard, you should provide a login hint before starting the Face Authentication module. The login hint can be phone, email, or identityId (that is, the ID of a user who has been successfully onboarded previously). The following image shows the identityId option.

IncdWelcome.getInstance().setFaceAuthenticationHint("identityId")

IncdOnboardingManager.shared.faceAuthenticationHint = “identityId”

await IncodeSdk.setFaceAuthenticationHint({ faceAuthenticationHint: 'identityId' });

IncodeOnboardingSdk.setFaceAuthenticationHint(identityId: "identityId");

cordova.exec(function (param) {
    console.log("FaceAuth hint set");
  }, function (err) {
    console.log("Error faceAuthHint: " + err);
  }, "Cplugin", "setFaceAuthenticationHint", ["identityId"]);

Low-code integration

A low-code integration allows you to configure Face Authentication completely on the Incode Dashboard and call SDK methods to start a Flow or Workflow.

If you use a Flow, and Face Authentication fails, the flow is aborted. If you use the preferred Workflow method, and Face Authentication fails, the user continues through the steps you configure for this scenario.

Full SDK integration

Full SDK integration allows you to setup Face Authentication inside a startOnboarding or Sections implementation method.

Step 1: Configure a Flow on Dashboard

On the Incode Dashboard, create a Flow that contains the Face Authentication module. Make a note of the Flow ID; you will need it in the next step.

To specify 1:1 or 1:N Face Authentication method and all other parameters please checkout this page.

Step 2: Setup a session

Set up a session using the Flow ID from the previous step as a configurationId, as shown in this image.

private SessionConfig getSimpleSession() {
        SessionConfig sessionConfig = new SessionConfig.Builder()
                .setConfigurationId("configurationId")
                .build();

        return sessionConfig;
    }

func createSessionConfiguration() -> IncdOnboardingSessionConfiguration {
  return IncdOnboardingSessionConfiguration(regionCode: "ALL",
                                            configurationId: "configurationId")
}

function getSimpleSession() {
    let sessionConfig: {
      region: 'ALL',
      configurationId: 'configurationId',
    };

    return sessionConfig;
  }

OnboardingSessionConfiguration getSimpleSession() {
  // Common configs
  IncodeOnboardingSdk.showCloseButton(allowUserToCancel: true);
  
  // Session config
  OnboardingSessionConfiguration sessionConfig = OnboardingSessionConfiguration(configurationId: "configurationId");
  
	return sessionConfig;
}

var config = new OnboardingConfiguration()
                .AddRegion("ALL")
                .AddConfigurationId("configurationId")
                .AllowUserToCancel(true);

function startSession(){
              cordova.exec(function(data) {
                       // Start the Incode moudles or sections from here
                       startOnboardingSection();                       
                       }, function(err) {
                        console.log(" startSession Error: "+ err);
                         // handle the error by showing some UI or alert.
                         callbackError('Nothing to echo.' +err);
                     }, "Cplugin", "setupOnboardingSession", ["configurationId",null,null,null]);
      }

Step 3: Create a Flow

Add Face Authentication to the Flow as shown here.

private FlowConfig getFlowConfig() {
    FlowConfig flowConfig = null;
    try {
        flowConfig = new FlowConfig.Builder()
                .addFaceAuthentication()
                .build();
    } catch (ModuleConfigurationException e) {
        e.printStackTrace();
    } catch (Exception e) {
        e.printStackTrace();
    }

    return flowConfig;
}

func createFlowConfiguration() -> IncdOnboardingFlowConfiguration {
  let flowConfig = IncdOnboardingFlowConfiguration()
  flowConfig.addFaceAuthentication()
  return flowConfig
}

function getFlowConfig(){
    let flowConfig = [
      { module: 'FaceAuthentication'},
    ];

    return flowConfig;
}

OnboardingFlowConfiguration getStraightforwardFlowConfig(){
 	OnboardingFlowConfiguration flowConfig = OnboardingFlowConfiguration();
  
  flowConfig.addFaceAuthentication();
  
  return flowConfig;
}


function getFlowConfig() {
  return [
    { module: "addFaceAuthentication" }
  ];
}

You can configure these additional parameters on all platforms:

autoCaptureTimeout-> Time interval in seconds after which manual capture mode is enabled. Defaults to 16.
captureAttempts-> Number of attempts user has to successfully authenticate. Defaults to 3
showTutorials-> Hide or show the capture tutorial before user enters the Selfie capture screen. Defaults to true.
eyesClosedCheckEnabled-> Prevent or allow users from capturing images with their eyes closed. Defaults to true.
lensesCheckEnabled-> Prevent or allow users from capturing images wearing their lenses. Defaults to true.
headCoverCheckEnabled-> Prevent or allow users from capturing images with their head covered. Defaults to true.
maskCheckEnabledPrevent or allow users from capturing images with masks on their face. Defaults to true.

Step 4: Use `startOnboarding` or Sections

`startOnboarding`

Call the startOnboarding method and provide sessions and Flow configurations you created previously, as shown here.

IncodeWelcome.getInstance().startOnboarding(activityContext, mSessionConfig, mFlowConfig, onboardingListener);

IncdOnboardingManager.shared.startOnboarding(sessionConfig: sessionConfig, flowConfig: flowConfig, delegate: self)

await IncodeSdk.startOnboarding({
        sessionConfig: sessionConfig,
        flowConfig: flowConfig,
      });

IncodeOnboardingSdk.startOnboarding(
  sessionConfig: sessionConfig,
  flowConfig: flowConfig,
  onSuccess: () {
    print('Start Onboarding completed!');
  },
  onError: (String error) {
    print('Start onboarding error: $error');
  },
);

Sections

Alternatively, you can call setupOnboardingSession with the session configuration from the step 2. Then call startOnboardingSection and provide the Flow configuration from step 3. The following image shows this approach.

IncodeWelcome.getInstance().setupOnboardingSession(sessionConfig, new OnboardingSessionListener() {

            @Override
            public void onOnboardingSessionCreated(String token, String interviewId, String region) {

              IncodeWelcome.getInstance().startOnboardingSection(this, mFlowConfig, new SectionOnboardingListener() {

                  @Override
                  public void onOnboardingSectionCompleted(String flowTag) {
                      // decided what to show next, ie. start a new section
                  }

                @Override
                  public void onFaceAuthenticationCompleted(@NonNull FaceAuthenticationResult faceAuthenticationResult) {
                      super.onFaceAuthenticationCompleted(faceAuthenticationResult);
                  }

                  @Override
                  public void onError(Throwable error) {
                      super.onError(error);
                  }

                  @Override
                  public void onUserCancelled() {
                      super.onUserCancelled();
                  }

            });
            }

            @Override
            public void onError(Throwable throwable) {
                doOnError(throwable);
            }

            @Override
            public void onUserCancelled() {
            }
        });

IncdOnboardingManager.shared.setupOnboardingSession(sessionConfig: sessionConfig) { result in
                print("session setup result: \(result)")
                IncdOnboardingManager.shared.startOnboardingSection(flowConfig: flowConfig, sectionTag: "faceAuth", delegate: self)
              }

IncodeSdk.setupOnboardingSession({
      sessionConfig: sessionConfig,
    })
      .then((sessionResult) => {
        /// 🚣 startOnboardingSection
        IncodeSdk.startOnboardingSection({
          flowConfig: flowConfig,
        })
          .then((onboardingSectionResult) => {
            console.log(`Onboarding section complete`);
          })
          .catch((e) => {
            console.log('Start onboarding section error', e);
          });
      })
      .catch((e) => {
        console.log('Set onboarding session error', e);
      });

IncodeOnboardingSdk.setupOnboardingSession(
      sessionConfig: sessionConfiguration,
      onError: (String error) {
        print('Incode onboarding session error: $error');
      },
      onSuccess: (OnboardingSessionResult result) {
        print('Incode Onboarding session created! $result');

        IncodeOnboardingSdk.startNewOnboardingSection(
          flowConfig: flowConfig,
          onError: (String error) {
            print('Incode onOnboardingSectionCompleted error: $error');
          },
          onOnboardingSectionCompleted: (flowTag) {
            print('Incode onOnboardingSectionCompleted');
          },
          onUserCancelled: () {
            print('Incode startNewOnboardingSection cancelled by user.');
          },
        );
      },
    );