Documentation
incode.com
  1. SDK Reference
  2. Incode WebSDK 2.0 Reference
  3. Individual Modules Catalog

Face Match Module

📘

This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation here. 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 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

PropertyTypeRequiredDescription
configFaceMatchConfig❌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;
};
OptionTypeRequiredDescription
matchingTypeFaceMatchVariant❌Which images to compare. Default 'selfieVsId'. Backend field name matchingType.
disableFaceMatchAnimationboolean❌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:

StatusDescription
idleInitial state.
loadingFetching face images and computing the match server-side.
animatingPlaying the reveal animation. Skipped when disableFaceMatchAnimation is true.
resultAnimation finished; result is on state.result (matched, liveness).
finishedTerminal.
errorFatal error.

The result state's data:

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

API methods

MethodPurpose
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