📘  
This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation [here](https://developer.incode.com/docs/web-sdk-reference). Contact your Incode Representative for upgrade information and check if you are a candidate for this upgrade.

Full rollout to all clients still TBD.

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](https://developer.incode.com/docs/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`.