Face Authentication

The Face Authentication module captures a returning user's face with the device camera and matches it against the face already enrolled for that user. It then returns a pass or fail result.

For an overview of this module and how it works, see Face Authentication.

How you use this module depends on your integration pattern. In Patterns 1 and 2, you add the module to a FlowConfig in code as shown on this page. In Pattern 3, you define your modules and configuration in Dashboard as a Flow or Workflow and reference it by ID with startFlow() or startWorkflow() as shown on Run Flows Configured in Dashboard.

Add Face Authentication

Add the module with one of the addFaceAuthentication overloads. Face Authentication runs against an existing enrolled user, so your Flow or Workflow must identify that user: for example, through your session configuration. Whether the module is available depends on your Incode Flow or Workflow configuration.

// Default configuration
flowConfigBuilder.addFaceAuthentication()

// Custom configuration
flowConfigBuilder.addFaceAuthentication(faceAuthentication)

// Default configuration
flowConfigBuilder.addFaceAuthentication();

// Custom configuration
flowConfigBuilder.addFaceAuthentication(faceAuthentication);

Face Authentication ships both a v1 (legacy View) and a v2 (Compose) capture UI; the active one depends on your Incode configuration. Contact your Incode representative to enable v2.

Example

The example below builds a FaceAuthentication module with tutorials shown, adds it to the flow, and listens for the result through onFaceAuthenticationCompleted().

val faceAuthentication = FaceAuthentication.Builder()
    .setShowTutorials(true)
    .build()

val flowConfig = FlowConfig.Builder()
    .addFaceAuthentication(faceAuthentication)
    .build()

val onboardingListener = object : IncodeWelcome.OnboardingListener() {
    override fun onFaceAuthenticationCompleted(faceAuthenticationResult: FaceAuthenticationResult) {
        // Face authentication completed
    }

    override fun onError(error: Throwable) {
        // Onboarding flow was aborted due to error
    }
}

IncodeWelcome.getInstance().startOnboarding(
    activityContext,
    sessionConfig,
    flowConfig,
    onboardingListener
)

FaceAuthentication faceAuthentication = new FaceAuthentication.Builder()
    .setShowTutorials(true)
    .build();

FlowConfig flowConfig = new FlowConfig.Builder()
    .addFaceAuthentication(faceAuthentication)
    .build();

IncodeWelcome.OnboardingListener onboardingListener = new IncodeWelcome.OnboardingListener() {
    @Override
    public void onFaceAuthenticationCompleted(@NonNull FaceAuthenticationResult faceAuthenticationResult) {
        // Face authentication completed
    }

    @Override
    public void onError(@NonNull Throwable error) {
        // Onboarding flow was aborted due to error
    }
};

IncodeWelcome.getInstance().startOnboarding(
    activityContext,
    sessionConfig,
    flowConfig,
    onboardingListener
);

Configuration Options

Configure the module with FaceAuthentication.Builder. The table below lists the most commonly used options.

For the complete option set, see FaceAuthentication.Builder in API Reference.

Result

Face Authentication delivers a FaceAuthenticationResult to the onFaceAuthenticationCompleted(faceAuthenticationResult) callback on OnboardingListener. Key fields include:

• isSuccess: true if face authentication succeeded; otherwise, false.
• customerUUID: The customer UUID associated with the authenticated face; null when unavailable.
• selfieBase64: The Base64-encoded selfie image captured during authentication; null when unavailable. Redacted from toString() to avoid leaking PII.
• encryptedSelfieBase64: Base64-encoded encrypted selfie image; null when unavailable. Redacted from toString() to avoid leaking PII.
• Fields inherited from BaseResult:
  • resultCode: The ResultCode for this result.
  • error: When resultCode is ERROR, the Throwable that caused it; otherwise, null.
  • deviceStats: The DeviceStats snapshot of the device state when the result was produced.
  • motionStatus: Device motion assessment during capture. One of the following:
    • UNCLEAR: Motion could not be determined; the default.
    • PASS: Device motion was within acceptable limits.
    • FAIL: Excessive device motion was detected.

The captured selfie fields are redacted from FaceAuthenticationResult.toString() to avoid leaking PII in logs.

Errors surface through OnboardingListener.onError(Throwable). This module can deliver a module-specific FaceAuthenticationException. This exception carries a FaceAuthenticationErrorCode. For example, isSpoofAttemptDetected() reports a detected spoof attempt.

For all fields, see FaceAuthenticationResult in API Reference.