Description

Face Authentication is a module within an onboarding flow where a selfie is taken and then is compared to a previously onboarded user.

Prerequisite

Face Authentication module has to be configured on the Incode dashboard. To specify 1:1 or 1:N Face Authentication method and all other parameters please checkout this page.

Integration options

Low-code integration

Using startFlow or startWorkflow methods

Full SDK integration

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

All the integration steps start with the initialization of the SDK:

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 1:1 Face Authentication method is configured on the dashboard, before starting the Face Authentication module a login hint should be provided, and as of now it must be a identityId, which references id of a successfully onboarded user:

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

Low code integration allows you to configure Face Authentication module completely on the Incode Omni dashboard and call SDK methods to start the flow or workflow.

Flows

For full guide about how to start a flow, please checkout this page

If Face Authentication fails the flow will be aborted, otherwise end-user will continue through the rest of modules within a flow.

Workflows

For full guide about how to start a workflow, please checkout this page

Use Workflow Builder on the Omni dashboard to specify what should be done when face authentication fails or succeeds.

Full SDK integration

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

Step 1: Configure a flow on Dashboard

Prerequisite is that a flow is created on Dashboard that contains Face Authentication module. To specify 1:1 or 1:N Face Authentication method and all other parameters please checkout this page.

Step 2: Setup a session

To setup a session use a flow ID from the previous step and provide it as a configurationId :

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 module to the flow:

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" }
  ];
}

Additionally, you can configure on all platforms these params:

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 startOnboarding method and provide previously created sessions and flow config.

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

Call setupOnboardingSession with the session configuration from the step 2) , and then call startOnboardingSection providing the flow configuration from the step 3)

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.');
          },
        );
      },
    );