# Face Match Module

<WebSDK2 />

The Face Match module compares two captured face images — typically the user's selfie versus the face cropped from their ID document — and returns a match decision plus a liveness verdict. Runs server-side using images already collected by the session.

> Follows the [backend-process pattern](doc:web-sdk-2-module-patterns#3-backend-process-modules) with an additional `animating` state for the result-reveal animation. See the patterns page for the shared lifecycle.

## Tag

`<incode-face-match>` is a standard Web Component. Importing the UI subpath registers the custom element; importing the CSS applies the module's styles.

```ts
import '@incodetech/web/face-match';
import '@incodetech/web/face-match/styles.css';
```

## Properties

| Property   | Type                      | Required | Description                                  |
| ---------- | ------------------------- | -------- | -------------------------------------------- |
| `config`   | `FaceMatchConfig`         | ❌        | Configuration options                        |
| `onFinish` | `() => void`              | ❌        | Called when the result has been acknowledged |
| `onError`  | `(error: string) => void` | ❌        | Called when an error occurs                  |

## Configuration

```typescript
type FaceMatchConfig = {
  matchingType?: 'selfieVsId' | 'selfieVsNfc' | 'idVsNfc' | 'nfc3Way' | 'secondId';
  disableFaceMatchAnimation?: boolean;
};
```

| Option                      | Type               | Required | Description                                                                                                                             |
| --------------------------- | ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `matchingType`              | `FaceMatchVariant` | ❌        | Which images to compare. Default `'selfieVsId'`. Backend field name `matchingType`.                                                     |
| `disableFaceMatchAnimation` | `boolean`          | ❌        | When `true`, skip the reveal animation and auto-advance after fetching the result. Useful for headless / silent flows. Default `false`. |

## State machine

`FaceMatchState` is a discriminated union over `status`:

| Status      | Description                                                                       |
| ----------- | --------------------------------------------------------------------------------- |
| `idle`      | Initial state.                                                                    |
| `loading`   | Fetching face images and computing the match server-side.                         |
| `animating` | Playing the reveal animation. Skipped when `disableFaceMatchAnimation` is `true`. |
| `result`    | Animation finished; result is on `state.result` (`matched`, `liveness`).          |
| `finished`  | Terminal.                                                                         |
| `error`     | Fatal error.                                                                      |

The `result` state's data:

```typescript
type FaceMatchResult = {
  matched: boolean | null; // OK = true, FAIL = false, UNKNOWN = null
  liveness: boolean | null;
};
```

## API methods

| Method                | Purpose                                                     |
| --------------------- | ----------------------------------------------------------- |
| `load()`              | Fetch images and compute match.                             |
| `animationComplete()` | Tell the manager the animation finished (when `animating`). |
| `continue()`          | Acknowledge the result and finish.                          |
| `reset()`             | After `finished` or `error`, return to idle.                |

Plus the universal lifecycle: `subscribe`, `getState`, `stop`.

## See also

* [Module: Selfie](doc:web-sdk-2-module-selfie-1): captures the selfie this module compares against
* [Module: ID Capture](doc:web-sdk-2-module-id-capture): captures the ID this module compares against
* [Module Patterns → backend-process](doc:web-sdk-2-module-patterns#3-backend-process-modules)
* [Individual Modules](doc:web-sdk-2-individual-modules)