# 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](https://developer.incode.com/docs/face-authentication).

How you use this module depends on your [integration pattern](https://developer.incode.com/docs/android-common-implementation-patterns#integration-patterns). 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](https://developer.incode.com/docs/android-run-flows-configured-online).

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

```kotlin
// Default configuration
flowConfigBuilder.addFaceAuthentication()

// Custom configuration
flowConfigBuilder.addFaceAuthentication(faceAuthentication)
```
```java
// 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()`.

```kotlin
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
)
```
```java
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.

| Setting                        | Description                                                                                                                                                                                                                                                     |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setShowTutorials`             | Shows a tutorial before the scan. Default is `true`.                                                                                                                                                                                                            |
| `setAutoCaptureTimeout`        | Sets the auto-capture timeout, in seconds.                                                                                                                                                                                                                      |
| `setCaptureAttempts`           | Sets the number of capture attempts.                                                                                                                                                                                                                            |
| `setMaskCheckEnabled`          | Enables local face-mask detection during capture. Default is `true`.                                                                                                                                                                                            |
| `setImageQualityCheckSeverity` | Sets how strict the image quality check is during capture.                                                                                                                                                                                                      |
| `setFaceOcclusionEnabled`      | Enables a face occlusion check. Requires the `model-face-occlusion` [dependency](https://developer.incode.com/docs/android-installation#declare-dependencies), or a `MissingModelFaceOcclusionDependencyException` is thrown when the check runs. |

For the complete option set, see `FaceAuthentication.Builder` in [API Reference](https://developer.incode.com/docs/android-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](https://developer.incode.com/docs/android-api-reference).