Face Match Module

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

📘
This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation here. We strongly recommend upgrading - contact your Incode Representative for upgrade information.

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

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

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:

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.

Tag

Properties

Configuration

State machine

API methods

See also