Skip to main content

v8.0.5

Introduction​

DOT Web Face Auto Capture is set of non-ui-component and ui-component web components to capture image of user's face.

non-ui-component is a web component that renders the video stream from an available phone or web camera to automatically capture an image of a user's face with the required quality.

ui-component is a web component that renders an overlay over video stream. Overlay includes a placeholder, camera control buttons and instructions to guide the user to position their face correctly.

[[supported-browsers]]

Supported Browsers​

DOT Web Face Auto Capture was tested with:

  • Chrome on desktop (Windows, Mac and Linux) and mobile (Android, iPhone)
  • @Deprecated Firefox on desktop (Windows, Mac and Linux) and mobile (Android)****
  • Edge on Windows
  • Safari on Mac, iPad and iPhone
  • WebView on Android*
  • SafariVC on iPad and iPhone**
  • WKWebView on iPad and iPhone***

Known issues:

*{sp}Some older Android phones can experience issues with camera stream initialization using WebRTC. Our web components will work on most of them, but camera stream could be slow and laggy. This issue is caused by device and can be experienced in any website using WebRTC in Android WebView.

**{sp}Components are tested with SafariVC on devices iPhone 7 and newer with iOS 15 or iPadOS 15 or newer. Older devices or iOS versions are not officially supported and might experience issues.

*** In order to run DOT Web Face Auto Capture in WKWebView on iPhone or iPad, allowsInlineMediaPlayback and mediaTypesRequiringUserActionForPlayback properties on WKWebViewConfiguration must be set to true.

****{sp} @Deprecated Firefox support for all Innovatrics web components is deprecated and will be discontinued in next major release.
Some older and/or low-end Android phones can experience issues with camera stream initialization using WebRTC when using Firefox browser. Our web components might display The webcam is already in use by another application error. This issue is caused by the Firefox's implementation of initialization of camera and can be experienced in any website using WebRTC in Firefox on Android. It is recommended to use other supported browsers in those cases.

When using components on MacOS with linked iPhone (using Apple ID) and enabled Continuity Camera setting, the camera stream from the iPhone might not get streamed correctly in the case user has an active Firewall protection from third-party Antivirus software.

When using components on Safari on MacOS with linked iPhone (using Apple ID) and enabled Continuity Camera setting, there may be multiple cameras present, which might not work as expected. Switching camera until correct camera is selected fixes the issue.

Video capture feature is not supported in Firefox for Android and Safari (and WebView) older than 16.4.

Privacy and security​

This component can only be used in secure contexts due to MediaDevices API used for handling camera access. A secure context is, in short, a page loaded using HTTPS or the file:/// URL scheme, or a page loaded from localhost. Before accessing any camera, the component must always get the user's permission. Browsers may offer a once-per-domain permission feature, but they must ask at least the first time, and the user has to specifically grant ongoing permission if they choose to do so. Browsers are required to display an indicator that shows that a camera or microphone is in use. More details can be found on https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#privacy_and_security[MDN docs^].

[[non-ui-component]]

Non-ui component​

Requirements​

Minimum required camera resolution for appropriate results is 720x720. Anything less is insufficient.

Initialization​

DOT Web Face Auto Capture can be installed via NPM, yarn or pnpm

npm install @innovatrics/dot-face-auto-capture

To manually integrate the DOT Web Face Auto Capture, download latest version from the https://github.com/innovatrics/dot-js-kit/releases[Github repository^]. Then add following line to dependencies in your package.json:

"dependencies": {
    "@innovatrics/dot-face-auto-capture": "file:innovatrics-dot-face-auto-capture-[VERSION].tgz"
},

where [VERSION] is the DOT Web Face Auto Capture version integrated. This installs dot-face-auto-capture as an external module that can then be used (just like any other module in the code). For example, one could do import '@innovatrics/dot-face-auto-capture'; in the app.

Usage​

Face auto capture component is a https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements[web component] which uses custom HTML <x-dot-face-auto-capture/> tag. Properties configuration needs to be passed into component after <x-dot-face-auto-capture/> tag was rendered.

import type {
  HTMLFaceCaptureElement,
  FaceConfiguration,
  CallbackImage,
  DetectedFace
} from "@innovatrics/dot-face-auto-capture";

import { useEffect } from "react";
import "@innovatrics/dot-face-auto-capture";

function FaceCamera(configuration: FaceConfiguration) {
  useEffect(() => {
    const faceAutoCaptureHTMLElement = document.getElementById(
      "x-dot-face-auto-capture"
    ) as HTMLFaceCaptureElement | null;

    if (faceAutoCaptureHTMLElement) {
      faceAutoCaptureHTMLElement.configuration = configuration;
    }
  });

  return <x-dot-face-auto-capture id="x-dot-face-auto-capture" />;
}

function Page() {
  function handleOnComplete(imageData: CallbackImage<DetectedFace>, content: Uint8Array) {
    // ...
  }

  function handleError(error: Error) {
    alert(error);
  }

  return (
    <FaceCamera
      camera={{ facingMode: "user" }}
      autoCapture={{
        candidateSelectionDurationMillis: 3000,
      }}
      onComplete={handleOnComplete}
      onError={handleError}
      sessionToken="1111-222-333-4444"
      transactionCountingToken="provide-the-token-here"
    />
  );
};

Alternatively, you can use useRef and useLayoutEffect to render a web component with its props.

import type { 
  FaceConfiguration, 
  HTMLFaceCaptureElement,
} from '@innovatrics/dot-face-auto-capture';

import { useLayoutEffect, useRef } from 'react';
import '@innovatrics/dot-face-auto-capture';

function FaceCamera(configuration: FaceConfiguration) {
  const ref = useRef<HTMLFaceCaptureElement | null>(null);

  useLayoutEffect(() => {
    const element = ref.current;

    if (element) {
      element.configuration = configuration;
    }
  }, [configuration]);

  return <x-dot-face-auto-capture id="x-dot-face-auto-capture" ref={ref} />;
}

iOS - Requesting DeviceMotion Permissions​

To utilize the device motion sensor and provide instructions for device_pitched instruction on iOS , it's necessary to invoke the DeviceMotionEvent.requestPermission() method and acquire user consent. This requirement is set by Apple and isn't specific to the DOT Web Face Auto Capture. The method returns a promise that yields a string – either "granted" or "denied". If the user has already granted permission, the promise will resolve instantly.

Unfortunately DeviceMotionEvent.requestPermission() could only be called on a "user gesture" event, such as a button click. Requesting permission without a user gesture event isn't feasible. Given that, DOT Web Face Auto Capture doesn't produce any suitable user gesture event, the method must be invoked from the parent component when a user gesture event takes place. For example, when user clicks a button "Continue to take selfie". Below is a TypeScript example illustrating the process:

type DeviceMotionEventWithPermissions = {
  requestPermission: () => Promise<PermissionState>;
} & DeviceMotionEvent;

try {
  const { requestPermission } = DeviceMotionEvent as unknown as DeviceMotionEventWithPermissions;

  if (typeof requestPermission === "function") {
    const response = await requestPermission();

    if (response === "granted") {
      // permissions granted
    } else {
      // permissions denied
    }
  }
} catch (error) {
  // handle error in standard way
}

Without this permission, the device_pitched instruction will not be available but the component will still work. Further information on this can be found in this https://dev.to/li/how-to-requestpermission-for-devicemotion-and-deviceorientation-events-in-ios-13-46g2[article^].

TypeScript​

Declaration file is bundled inside package. To use with TypeScript, import types from @innovatrics/dot-face-auto-capture.

import type { FaceConfiguration, CallbackImage, DetectedFace } from "@innovatrics/dot-face-auto-capture";

Hosting dot-assets files​

During the initialization phase of the component, the component loads the required assets files, such as WASM binary files, javascript chunks, license etc, via HTTP fetch request. Please note that we do not provide any hosting for those files. That's why it is essential that the customer provides the component with all files from our distribution. To do so, please:

  1. copy dot-assets directory from our distribution into your distribution every time you update to new version of the component. If you are using package manager, you can find dot-assets directory in node_modules/@innovatrics/dot-face-auto-capture/dot-assets.

  2. copy iengine.lic (or license.lic) file into dot-assets folder in your distribution.

Please note that dot-assets files need to be hosted at the same URL as your app - https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker#:~:text=This%20script%20must%20obey%20the%20same%2Dorigin%20policy.[same-origin^]. Because of that, we do not recommend using any CDN, as it will probably not function properly.

Structure of the directory in our distribution​

@innovatrics/
|__ dot-face-auto-capture/
    |__ dot-assets/ <-- copy this directory
        |__ face/
            |__ wasm/
                |-- sam.wasm
                |-- sam_simd.wasm
            |-- dot-<CHUNK_HASH>.js
            ...
        |__ wasm/
            |-- acp_core_wasm_bg.wasm
    |-- package.json
    |-- README.md
    ...

Example of the dot-assets dir structure in integrator's application​

public/
  |__ dot-assets/ <-- do not change the name or structure of this directory (only add folders for another components when needed)
      |__ face/
          |__ wasm/
              |-- sam.wasm
              |-- sam_simd.wasm
          |-- dot-<CHUNK_HASH1>.js
          |-- dot-<CHUNK_HASH2>.js
          ...
      ... <-- if you are using other components (e.g. document), the folders with assets of these components will be here (eg. document/)
      |__ wasm/
          |-- acp_core_wasm_bg.wasm
      |-- iengine.lic
  ...

By default, the component will try to fetch the desired files from <PROJECT_ORIGIN>/dot-assets/**. This can be changed using assetsDirectoryPath property. For example, if assetsDirectoryPath=/my-directory property is provided, the component will try to fetch the desired files from <PROJECT_ORIGIN>/my-directory/dot-assets/**. Please note that structure and the name of the directory must be preserved. For more information, check out our https://github.com/innovatrics/dot-web-samples[samples on Github] where you can find real examples of how to host files in various technologies such as React, Angular, Vue, etc.

Please note, that if you use multiple components (e.g. face and document) you need to make sure, that all of the needed files are present in appropriate folders:

public/
  |__ dot-assets/ <-- do not change the name or structure of this directory (only add folders for another components when needed)
      |__ face/ <-- copied from @innovatrics/dot-face-auto-capture
          |__ wasm/
              |-- sam.wasm
              |-- sam_simd.wasm
          |-- dot-<CHUNK_HASH1>.js
          |-- dot-<CHUNK_HASH2>.js
      |__ another_component/ <-- copied from another components' node_modules
          |__ wasm/
              |-- sam.wasm
              |-- sam_simd.wasm
          |-- dot-<CHUNK_HASH1>.js
          |-- dot-<CHUNK_HASH2>.js
      ...
  ...

Troubleshooting​

If you are having difficulties with hosting wasm files, check your browser console in dev tools. You should see an error message with more details about the problem. It's also a good idea to look at the network tab in the developer tools and check that the wasm file has been loaded correctly. Please pay close attention to the actual response of the wasm load request, as an HTTP 200 status does not necessarily mean that the wasm file was loaded correctly. If you see application/wasm in response type, then wasm file was loaded correctly. If you see e.g. text/html in response type, then wasm file was not loaded correctly.

Licensing​

In order to support wide adoption of the components, a free mode was developed in addition to the premium mode used by licensed customers.

Free mode​

Components run in the free mode by default. This mode does not impose any feature limits, it just displays an watermark overlay over the component, to indicate not-licensed deployment. The overlay looks as on the image below:

freemium-overlay

Premium​

To run components in premium mode, acp_core_wasm_bg.wasm and valid license files are needed. Additionally, if transaction reporting is enabled, a valid transaction token needs to be provided as a property (see transactionCountingToken in properties). To initialize WASM binary file please follow a steps in [Hosting WASM files](#Hosting WASM files). To use your license file you need to copy it to project public directory within dot-assets directory as <PROJECT_ORIGIN>/dot-assets/iengine.lic. By default, the component will try to fetch the desired license file from <PROJECT_ORIGIN>/dot-assets/iengine.lic or <PROJECT_ORIGIN>/dot-assets/license.lic*. This can be changed using assetsDirectoryPath property.

*{sp}Please note that fetching license from <PROJECT_ORIGIN>/dot-assets/license.lic by default is deprecated and will be removed in future versions. Please use <PROJECT_ORIGIN>/dot-assets/iengine.lic instead.

If one of the following steps fails, then component will run in Freemium mode:

  • WASM binary file not found
  • license file not found
  • license is not valid
  • transaction token is not valid or provided (if transaction reporting is enabled)

In order to obtain the license (and/or transaction token), please contact your Innovatrics' representative.

[[properties]]

Properties​

  • (Optional) object camera - Camera configuration
  • function onComplete – Callback on successful image capture
  • function onError – Callback in the case that an error occurred (see handling-errors)
    • (e: Error) => void
  • (Optional) string assetsDirectoryPath - Path to the dot-assets directory
  • (Optional) string sessionToken – Unique identifier of the session
  • (Optional) string transactionCountingToken – Unique identifier for the transaction counting feature
  • (Optional) object autoCapture - Auto capture configuration
    • (Optional) [2000] number candidateSelectionDurationMillis - Duration of the candidate selection phase in milliseconds
  • (Optional) object qualityAttributeThresholds - Detection configuration
    • (Optional) object confidence - Detection confidence threshold
      • (Optional) number min - Minimum confidence threshold
    • (Optional) object size - Face size configuration
      • (Optional) number min - Minimum face size ratio relative to shorter side of the camera resolution
      • (Optional) number max - Maximum face size ratio relative to shorter side of the camera resolution
    • (Optional) object sharpness - Sharpness configuration
      • (Optional) number min - Minimum sharpness threshold
    • (Optional) object brightness - Brightness configuration
      • (Optional) number min - Minimum brightness threshold
      • (Optional) number max - Maximum brightness threshold
    • (optional) object edgeDistanceToImageShorterSideRatio - Edge distance configuration
      • (Optional) number min - Minimum edge distance threshold
    • (Optional) object devicePitchAngle - Device pitch angle configuration
      • (Optional) number max - Maximum device pitch angle in degrees
  • (Optional) HTMLElement styleTarget - Provide an alternate DOM node to inject styles. DOM node has to exist inside DOM before auto-capture component is initialized. This is useful when rendering components in a shadow DOM. By default, the styles are injected into the <head> element of the document. See style-target example for more details.
  • (Optional) ['AUTO_CAPTURE'] captureMode - Defines a strategy for how a detection captures the desired image

[[callback-params]]

Callback parameters​

[[thresholds-presets]]

Thresholds presets​

DOT Web Face Auto Capture uses multiple thresholds presets for detection configuration based on different conditions. Currently, there are two presets:

MOBILE - Thresholds for mobile devices​

  • confidence
    • min: 0.4
  • sharpness
    • min: 0.25
  • brightness
    • min: 0.2
    • max: 0.85
  • edgeDistanceToImageShorterSideRatio
    • min: 0.05
  • devicePitchAngle
    • max: 30

DESKTOP - Thresholds for desktop devices​

  • confidence
    • min: 0.4
  • sharpness
    • min: 0.25
  • brightness
    • min: 0.2
    • max: 0.85
  • edgeDistanceToImageShorterSideRatio
    • min: 0.05
  • devicePitchAngle
    • max: 30

If user decides to use custom threshold using qualityAttributeThresholds property, it will override value in all presets. All customizable thresholds can be adjusted in the range from 0 to 1 (excluding devicePitchAngle, which accepts degrees).

[[multi-capture]]

Multi capture​

Face auto capture component allows you to capture an unlimited number of faces without the need to reinitialize the webcam and detector. Component calls onComplete callback on every captured face photo. When onComplete is called, detection is paused. Camera stream and face detector stay initialized. Component is in waiting state. You should implement a custom UI for waiting state (e.g. overlay over our component). We provide a default UI, but it is not customizable.

[[capture-mode]]

Capture mode​

Defines a strategy for how a detection captures the desired image.

[[capture-mode:auto-capture]]

Auto capture​

It is an automated process that attempts to capture multiple valid images and selects the best one from them. If the component captures at least two valid images, it enters a phase called candidate selection. During this phase, which lasts 2000 milliseconds by default, the component continues to collect valid images. Once this phase is complete, the best image is selected and returned by the component using the onComplete callback.

The duration of the candidate selection phase can be customized using the candidateSelectionDurationMillis property.

[[capture-mode:wait-for-request]]

Wait for request​

It is a manual process that allows you to capture an image on request. In this mode, the component is ready and waiting for your command. More details about how to request an image can be found in control-events. Once the component receives a request, it returns either the first image or the first valid image using the onComplete callback.

Please note that in this mode, the candidate selection phase used in capture-mode:auto-capture is ignored.

Implement dispatch 'continue-detection' event​

import { dispatchControlEvent, FaceCustomEvent, ControlEventInstruction } from "@innovatrics/dot-face-auto-capture/events";

function continueDetection() {
  dispatchControlEvent(FaceCustomEvent.CONTROL, ControlEventInstruction.CONTINUE_DETECTION)
};

Without importing @innovatrics/dot-face-auto-capture/events.

function continueDetection() {
  document.dispatchEvent(
    new CustomEvent("face-auto-capture:control", {
      detail: { instruction: "continue-detection" },
    }),
  );
}

[[handling-errors]]

Handling errors​

When an error occurs, we call onError callback with one parameter of type Error. We set name property to AutoCaptureError, and also message with more details. Component renders default UI for error state, but is not customizable, and integrator should implement own error handling. Component uses the MediaDevices API that provides access to connected media input devices like cameras and microphones. If the user denies permission to access or the webcam is not present, an error is thrown. We provide original error thrown by browser inside cause property of the error object. List of possible errors can be found on https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#exceptions[MDN docs^].

Error example:

{
  name: "AutoCaptureError",
  message: "The webcam is already in use by another application",
  cause: DOMException: Could not start video source // Original error thrown by browser MediaDevices API
}

[[ui-component]]

Ui component​

Requirements​

Both components must be wrapped in parent div with position: relative.

<div style={{position: "relative"}}>
  <FaceUi />
  <FaceCamera
    camera={{
      facingMode: "user",
    }}
    onComplete={handleComplete}
    onError={handleError}
    transactionCountingToken="provide-the-token-here"  
  />
</div>

Initialization​

UI component can be installed via NPM, yarn or pnpm

npm install @innovatrics/dot-auto-capture-ui

To manually integrate UI component, download latest version from the https://github.com/innovatrics/dot-js-kit/releases[Github repository^]. Add following line to dependencies in your package.json:

"dependencies": {
    "@innovatrics/dot-auto-capture-ui": "file:innovatrics-dot-auto-capture-ui-[VERSION].tgz",
}

where [VERSION] is the DOT Web Face Auto Capture version integrated. This installs dot-auto-capture-ui as an external module that can be used (just like any other module in the code). For example, one could do import '@innovatrics/dot-auto-capture-ui'; in the app.

Usage​

Face auto capture UI component is an https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements[web component] which uses custom HTML <x-dot-face-auto-capture-ui /> tag. Properties configuration needs to be passed into component after <x-dot-face-auto-capture-ui /> tag was rendered.

To see an example of using the component together with ui-component, see example-of-using-components-together.

import type { FaceUiConfiguration, HTMLFaceUiElement } from "@innovatrics/dot-auto-capture-ui/face";

import { useEffect } from "react";
import "@innovatrics/dot-auto-capture-ui/face";

 function FaceUi(configuration: FaceUiConfiguration) {
  useEffect(() => {
    const uiElement = document.getElementById("x-dot-face-auto-capture-ui") as HTMLFaceUiElement | null;

    if (uiElement) {
      uiElement.configuration = configuration;
    }
  });

  return <x-dot-face-auto-capture-ui id="x-dot-face-auto-capture-ui" />;
}

Alternatively, you can use useRef and useLayoutEffect to render a web component with its props.

import type { FaceUiConfiguration, HTMLFaceUiElement } from "@innovatrics/dot-auto-capture-ui/face";

import { useLayoutEffect, useRef } from "react";
import "@innovatrics/dot-auto-capture-ui/face";

function FaceUi(configuration: FaceUiConfiguration) {
  const ref = useRef<HTMLFaceUiElement| null>(null);

  useLayoutEffect(() => {
    const element = ref.current;

    if (element) {
      element.configuration = configuration;
    }
  }, [configuration]);

  return <x-dot-face-auto-capture-ui id="x-dot-face-auto-capture-ui" ref={ref} />;
};

TypeScript​

Declaration files are bundled inside package. Just import types from @innovatrics/dot-auto-capture-ui/face.

Properties​

  • (Optional) string placeholder - One of the predefined placeholders in component that can be selected

    • 'circle-solid'
    • 'square-rounded-dash'
    • 'square-rounded-solid'
    • 'square-dash'
    • 'square-solid'

  • (Optional) object instructions - Modification of default messages for localization or customization

    • (Optional) ['Stay still…'] string candidate_selection - Shown when all validations are passed, i.e. the image is suitable for capture
    • (Optional) ['Move back'] string face_too_close - Shown when the face is too close to the camera
    • (Optional) ['Move closer'] string face_too_far - Shown when the face is too far from the camera
    • (Optional) ['Center your face'] string face_centering - Shown when the face is not centered in the placeholder
    • (Optional) ['Position your face into the circle'] string face_not_present - Shown when no face is detected
    • (Optional) ['Position your face into the circle'] string left_eye_not_present - Shown when left eye is not detected (from the person's perspective)
    • (Optional) ['Position your face into the circle'] string right_eye_not_present - Shown when right eye is not detected (from the person's perspective)
    • (Optional) ['Position your face into the circle'] string mouth_not_present - Shown when mouth is not detected
    • (Optional) ['Turn face against light'] string sharpness_too_low - Shown when the face in the image is not sharp enough
    • (Optional) ['Turn face against light'] string brightness_too_low - Shown when the image is too dark
    • (Optional) ['Less light needed'] string brightness_too_high - Shown when the image is too bright.
    • (Optional) ['Hold your phone at eye level'] string device_pitched - Shown when the device is pitched too much.

  • (optional) object styling - Modification of styling properties

    • (Optional) string backdropColor - To customize the color of the default face placeholder backdrop. E.g.: 'rgba(10, 10, 10, 0.5)'. If you prefer not to use the backdrop, you can set the backdropColor to 'none'
    • (Optional) object theme - Modification of theme properties.
      • (Optional) colors - To customize colors of following properties
        • (Optional) ['white'] color placeholderColor - Color of the placeholder lines
        • (Optional) ['#00BFB2'] color placeholderColorSuccess - Color of the placeholder lines when all validations are passed
        • (Optional) ['white'] color instructionColor - Instruction background color
        • (Optional) ['#00BFB2'] color instructionColorSuccess - Instruction background color when all validations are passed
        • (Optional) ['black'] color instructionTextColor - Instruction text color
      • (Optional) font - To customize font with following properties
        • (Optional) ['Montserrat'] string family - Font family. Please note that the chosen font must be installed and available in the styles of the web components for it to display correctly.
        • (Optional) [14] number minimumSize - Minimum font size, from which the actual font size is calculated relative to the component width/height
        • (Optional) ['normal'] string style - Font style
        • (Optional) [600] string|number weight - Font weight

  • (Optional) appStateInstructions - Modification of default messages for component state

    • (Optional) loading - Component loading state
      • (Optional) ['Loading. Please wait.'] string text - Text shown while component is loading
      • (Optional) [true] boolean visible - Show/hide loading instruction while component is loading
    • (Optional) waiting - Component waiting state
      • (Optional) ['Waiting for input'] string text - Text shown while component is waiting
      • (Optional) [true] boolean visible - Show/hide waiting instruction while component is waiting

  • (Optional) object control - Modification of control properties

    • (Optional) [false] boolean showDetectionLayer - Show/hide detection layer on top of component
    • (Optional) [false] boolean showCameraButtons - Show/hide camera buttons (switch camera and toggle mirror) on top of component

  • (Optional) HTMLElement styleTarget - Provide an alternate DOM node to inject styles. DOM node has to exist inside DOM before auto-capture component is initialized. This is useful when rendering components in a shadow DOM. By default, the styles are injected into the <head> element of the document. See style-target example for more details.

Example how to use UI properties:

<FaceUi
  styling={theme={{ colors: { placeholderColor: "green" }, font: { style: 'italic' } }}}
  control={{
    showDetectionLayer: true,
    showCameraButtons: true,
  }}
  placeholder="circle-solid"
  instructions={{ candidate_selection: "Candidate selection" }}
  appStateInstructions={{ loading: { text: "Component is loading", visible: true } }}
/>

Example how to use backdropColor prop for the default face placeholder backdrop:

<FaceUi
  styling={
    theme={{ colors: { placeholderColor: "green" }, font: { style: 'italic' } }}, 
    backdropColor: "rgba(10, 10, 10, 0.5)"
  }
  control={{
    showDetectionLayer: true,
    showCameraButtons: true,
  }}
  instructions={{ candidate_selection: "Candidate selection" }}
  appStateInstructions={{ loading: { text: "Component is loading", visible: true } }}

/>

Example how to import fonts (using head in main html file):

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="" href="" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Title</title>
    <!-- import font in the head -->
    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <link href="https://fonts.googleapis.com/css2?family=Montserrat&display=swap" rel="stylesheet">
    <!------->
  </head>
</html>

[[style-target]] Example how to use styleTarget prop with ui-component when using Shadow DOM: This approach also works for non-ui-component.

import type { FaceUiConfiguration, HTMLFaceUiElement } from "@innovatrics/dot-auto-capture-ui/face";
import { useEffect } from "react";

import "@innovatrics/dot-auto-capture-ui/face";

function FaceUi(configuration: FaceUiConfiguration) {
  useEffect(() => {
    const uiElement = document.getElementById(
      "x-dot-face-auto-capture-ui"
    ) as HTMLFaceUiElement | null;

    const styleNode = document.createElement('div');
    
    uiElement?.shadowRoot?.append(styleNode);

    if (uiElement) {
       uiElement.configuration = {
        ...configuration,
        styleTarget: styleNode,
      };
    }
  });

  return <x-dot-face-auto-capture-ui id="x-dot-face-auto-capture-ui" />;
}

HTML of example above will look like this:

<x-dot-face-auto-capture-ui id="x-dot-face-auto-capture-ui">
  #shadow-root (open)
    <div> 
      <style data-styled="active" data-styled-version="6.1.0">
        /* CSS styles will be injected here*/
      </style>
    </div>
</x-dot-face-auto-capture-ui>

[[custom-events]]

Custom Events - Optional​

Communication between components is based on custom events. Ui component is mostly listening to events dispatched by non-ui component. In case of CONTROL event, ui component dispatches control events to control non-ui component.

When using default face-auto-capture-ui component, only dispatch continue-detection event has to be implemented to use multi-capture.

Type of Events​

Currently all events being used are described in this section. These are sufficient to build custom UI layer.

  • enum FaceCustomEvent - Event names dispatched by components

    • CONTROL = 'face-auto-capture:control - Events dispatched from 'ui' component to control non-ui component. Described in control-events section

  • CAMERA_PROPS_CHANGED = 'face-auto-capture:camera-props-changed' - Notifies UI when camera properties has changed

    • INSTRUCTION_CHANGED = 'face-auto-capture:instruction-changed' - Notifies the UI when the instruction has changed and whether it has been escalated
    • STATE_CHANGED = 'face-auto-capture:state-changed' - Notifies UI when state of non-ui component has changed
    • DETECTION_CHANGED = 'face-auto-capture:detection-changed' - Notifies UI when face is detected. Used in Detection Layer, has no effect if showDetectionLayer = false
    • VIDEO_ELEMENT_SIZE = 'face-auto-capture:video-element-size' - Notifies UI when HTML video element size has changed

  • enum ComponentCustomEvent - Event names dispatched by components

    • REQUEST_CAPTURE - dot-custom-event:request-capture - Event dispatched from outside of non-ui-component to request capture when component is running in WAIT_FOR_REQUEST capture mode. Described in control-events section

Usage​

Import @innovatrics/dot-face-auto-capture/events to use event types and and dispatch control events.

Listening to the Events​

All event listeners are already implemented in default face-auto-capture-ui component. Skip this section if you are using default ui component.

All FaceCustomEvent events, except CONTROL, are dispatched by Face Auto Capture non-ui component. Ui component listens to these events to make appropriate changes. See the example below how to register event listeners.

import type { 
  CameraPropsChangeEvent, 
  CameraStateChangeEvent, 
  VideoElementSizeChangeEvent, 
  FaceInstructionChangeEvent 
  DetectedFaceChangeEvent
} from "@innovatrics/dot-face-auto-capture/events";
import { FaceCustomEvent } from "@innovatrics/dot-face-auto-capture/events";
import type { 
  AppState, 
  FaceInstructionCode, 
  Resolution, 
  AutoCaptureError 
} from "@innovatrics/dot-face-auto-capture";
import { useEffect, useState } from "react";

export function Events() {
  const [instructionCode, setInstructionCode] = useState<{ code?: FaceInstructionCode; isEscalated: boolean }>();
  const [cameraResolution, setCameraResolution] = useState<Resolution | undefined>();
  const [isMirroring, setIsMirroring] = useState<boolean | undefined>();
  const [appState, setAppState] = useState<AppState | undefined>();
  const [error, setError] = useState<AutoCaptureError | undefined>();
  const [videoElementSize, setVideoElementSize] = useState<DOMRect | undefined>();
  const [detectedFaceCorners, setDetectedFaceCorners] = useState<DetectedFaceCorners | undefined>();

  useEffect(() => {
    function handleInstruction(event: FaceInstructionChangeEvent) {
      setInstructionCode({
        code: event?.detail?.instructionCode,
        isEscalated: event?.detail?.isEscalated ?? false,
      });
    }

    function handleCameraProps(event: CameraPropsChangeEvent) {
      setCameraResolution(event?.detail?.cameraResolution);
      setIsMirroring(event?.detail?.isMirroring);
    }

    function handleAppState(event: CameraStateChangeEvent) {
      setAppState(event?.detail?.appState);

      const error = event?.detail?.error;

      if (error) {
        setError(error);
      }
    }

    function handleVideoElementSize(event: VideoElementSizeChangeEvent) {
      setVideoElementSize(event.detail?.size)
    };

    function handleDetectedFace(event: DetectedFaceChangeEvent) {
      setDetectedFaceCorners(event?.detail?.detectedCorners)
    }

    document.addEventListener(FaceCustomEvent.INSTRUCTION_CHANGED, handleInstruction);
    document.addEventListener(FaceCustomEvent.CAMERA_PROPS_CHANGED, handleCameraProps);
    document.addEventListener(FaceCustomEvent.STATE_CHANGED, handleAppState);
    document.addEventListener(FaceCustomEvent.VIDEO_ELEMENT_SIZE, handleVideoElementSize)
    document.addEventListener(FaceCustomEvent.DETECTION_CHANGED, handleDetectedFace)

    return () => {
      document.removeEventListener(FaceCustomEvent.INSTRUCTION_CHANGED, handleInstruction);
      document.removeEventListener(FaceCustomEvent.CAMERA_PROPS_CHANGED, handleCameraProps);
      document.removeEventListener(FaceCustomEvent.STATE_CHANGED, handleAppState);
      document.removeEventListener(FaceCustomEvent.VIDEO_ELEMENT_SIZE, handleVideoElementSize);
      document.removeEventListener(FaceCustomEvent.DETECTION_CHANGED, handleDetectedFace)
    };
  }, [])
}

Without importing @innovatrics/dot-face-auto-capture/events you can use values of FaceCustomEvent directly.

const instructionChangeEvent = "face-auto-capture:instruction-changed";

function handleInstructionChange(event) {
  console.log(event.detail.instructionCode)
  console.log(event.detail.isEscalated)
}

document.addEventListener(instructionChangeEvent, handleInstructionChange);

/**
 * remove event listener when you're done
 */
document.removeEventListener(instructionChangeEvent, handleInstructionChange);

[[control-events]]

Control Events​

Control events are dispatched from outside of non-ui-component to control it.

FaceCustomEvent.CONTROL​

Events are dispatched from ui-component to control non-ui-component.

  • enum ControlEventInstruction
    • CONTINUE_DETECTION = 'continue-detection' - Controls multi-capture
    • SWITCH_CAMERA = 'switch-camera' - Notifies Face Auto Capture to use different camera
    • TOGGLE_MIRROR = 'toggle-mirror' - Notifies Face Auto Capture to mirror video stream
import { dispatchControlEvent, FaceCustomEvent, ControlEventInstruction } from "@innovatrics/dot-face-auto-capture/events";

export function Dispatch() {
  function continueDetection() {
    dispatchControlEvent(FaceCustomEvent.CONTROL, ControlEventInstruction.CONTINUE_DETECTION)
  }

  function switchCamera() {
    dispatchControlEvent(FaceCustomEvent.CONTROL, ControlEventInstruction.SWITCH_CAMERA)
  }

  function toggleMirror() {
    dispatchControlEvent(FaceCustomEvent.CONTROL, ControlEventInstruction.TOGGLE_MIRROR)
  }

  return (
    <div>
      <button onClick={continueDetection}>Continue detection</button>
      <button onClick={switchCamera}>Switch camera</button>
      <button onClick={toggleMirror}>Mirror camera</button>
    </div>
  )
}

Without importing @innovatrics/dot-face-auto-capture/events you can use values of FaceCustomEvent and ControlEventInstruction directly.

function continueDetection() {
  document.dispatchEvent(
    new CustomEvent("face-auto-capture:control", { 
      detail: { instruction: "continue-detection" },
    }),
  );
}

ComponentCustomEvent.REQUEST_CAPTURE​

  • enum RequestCaptureInstruction
    • FIRST_FRAME = 'first-frame' - Notifies Face Auto Capture to capture the very first image right after capturing this event. Validation and detection results are not evaluated in the process
    • FIRST_VALID_FRAME = 'first-valid-frame' - Notifies Face Auto Capture to capture the very first valid image right after capturing this event. Validation and detection results are evaluated in the process
import { dispatchCaptureEvent, ComponentCustomEvent, RequestCaptureInstruction } from "@innovatrics/dot-face-auto-capture/events";

export function Dispatch() {
  function captureAnyImage() {
    dispatchCaptureEvent(ComponentCustomEvent.REQUEST_CAPTURE, RequestCaptureInstruction.FIRST_FRAME)
  }

  function captureValidImage() {
    dispatchCaptureEvent(ComponentCustomEvent.REQUEST_CAPTURE, RequestCaptureInstruction.FIRST_VALID_FRAME)
  }

  return (
    <div>
      <button onClick={captureAnyImage}>Capture any image</button>
      <button onClick={captureValidImage}>Capture valid image</button>
    </div>
  )
}

Without importing @innovatrics/dot-face-auto-capture/events you can use values of ComponentCustomEvent and RequestCaptureInstruction directly.

function captureAnyImage() {
  document.dispatchEvent(
    new CustomEvent("dot-custom-event:request-capture", { 
      detail: { instruction: "first-frame" },
    }),
  );
}

function captureValidImage() {
  document.dispatchEvent(
    new CustomEvent("dot-custom-event:request-capture", { 
      detail: { instruction: "first-valid-frame" },
    }),
  );
}

[[example-of-using-components-together]]

Example of using components together​

import type { CallbackImage, DetectedFace } from "@innovatrics/dot-face-auto-capture";
import { 
  dispatchControlEvent, 
  FaceCustomEvent, 
  ControlEventInstruction 
} from "@innovatrics/dot-face-auto-capture/events";

import FaceCamera from "./FaceCamera";
import FaceUi from "./FaceUi";

function FaceAutoCapture() {
  function handleOnComplete({ image, data }: CallbackImage<DetectedFace>, content: Uint8Array) {
    // Includes result image
    console.log(image);
    // Includes detection data (such as confidence, corners, etc.), and image resolution
    console.log(data);
  }

  function handleError(error: Error) {
    alert(error);
  }

  function handleContinueDetection() {
    dispatchControlEvent(FaceCustomEvent.CONTROL, ControlEventInstruction.CONTINUE_DETECTION)
  }

  return (
    <div>
      <button onClick={handleContinueDetection}>Continue detection</button>
      <div style={{ position: "relative" }}>
        <FaceUi />
        <FaceCamera
          camera={{ facingMode: "user" }}
          onComplete={handleOnComplete}
          onError={handleError}
          transactionCountingToken="provide-the-token-here"
        />
      </div>
    </div>
  );
}

Code Samples​

See also https://github.com/innovatrics/dot-web-samples[DOT Web Samples, window="_blank"] showing the usage of DOT Web Auto Capture components in different front-end technologies like React, Angular...

Download​

https://github.com/innovatrics/dot-js-kit/releases[Github repository^]

Appendix​

Changelog

8.0.5 - 2026-04-15​

Changed​

  • Changed file name in /dot-assets folder from dot_embedded_bg.wasm to acp_core_wasm_bg.wasm

8.0.4 - 2026-02-23​

  • Incremental version upgrade

8.0.3 - 2026-02-12​

Changed​

  • Improved security measures and analytics

8.0.2 - 2026-01-14​

Changed​

  • Improved security measures and enhanced protection against vulnerabilities

8.0.1 - 2025-12-29​

  • Incremental version upgrade

8.0.0 - 2025-12-15​

Changed​

  • BREAKING CHANGE: Component configuration refactoring:
    • Non-UI component: property cameraOptions renamed to configuration
    • Non-UI component: HTMLFaceCaptureElement.cameraOptions renamed to HTMLFaceCaptureElement.configuration
    • Non-UI component: FaceCameraProps type renamed to FaceConfiguration
    • Non-UI component: thresholds property renamed to qualityAttributeThresholds
    • Non-UI component: callback onPhotoTaken renamed to onComplete
    • Non-UI component: callback parameter data renamed to imageData
    • UI component: property props renamed to configuration
    • UI component: HTMLFaceUiElement.props renamed to HTMLFaceUiElement.configuration
    • UI component: FaceUiProps type renamed to FaceUiConfiguration
    • UI component: showCameraButtons moved to nested control object (control.showCameraButtons)
    • UI component: showDetectionLayer moved to nested control object (control.showDetectionLayer)
    • UI component: backdropColor moved to nested styling object (styling.backdropColor)
    • UI component: theme moved to nested styling object (styling.theme)
  • BREAKING CHANGE Complete restructure of threshold public API (breaking change):
    • faceConfidence → confidence
    • sharpnessThreshold → sharpness
    • brightnessHighThreshold and brightnessLowThreshold → brightness
    • minFaceSizeRatio and maxFaceSizeRatio → size
    • devicePitchAngleThreshold → devicePitchAngle
    • outOfBoundsThreshold → edgeDistanceToImageShorterSideRatio
  • Changed default analytics provider from Countly to Innovatrics Metrics Middleware
  • BREAKING CHANGE Transaction reporting is now enabled by default (transactionCountingToken required in initialization phase when transaction reporting is included in license)
  • BREAKING CHANGE Removed ELLIPSE_SOLID, MAN_SOLID and WOMAN_SOLID placeholders

Deprecated​

  • Firefox browser support is deprecated due to incompatibility with required web platform features and will be discontinued in the next major release. A warning message will be displayed on localhost when using Firefox.

7.7.0 - 2025-11-20​

### Added

  • Video capture (only with Digital Identity Service)
  • isVideoCaptureEnabled to enable Video Capture

Changed​

  • update SAM to version 1.50.5

7.6.1 - 2025-10-17​

  • Incremental version upgrade

7.6.0 - 2025-10-16​

  • Incremental version upgrade

7.5.1 - 2025-10-06​

Fixed​

  • Increasing memory usage after each init

7.5.0 - 2025-08-21​

### Added

  • transactionCountingToken property to provide token for transaction reporting
  • Transaction reporting (for licenses with enabled transaction reporting)

Fixed​

  • Improved data integrity and stability fixes

Changed​

  • update SAM to version 1.50.2

7.4.0 - 2025-07-09​

Added​

  • candidateSelectionDurationMillis property to CameraOptions

Changed​

  • default candidate selection duration changed to 2000ms
  • update SAM to version 1.49.1

7.3.3 - 2025-06-16​

Added​

  • note in documentation about Apple Continuity Camera

Fixed​

  • loading animation not visible after request for camera permission has been accepted

7.3.2 - 2025-04-25​

Fixed​

  • documentation typo

7.3.1 - 2025-04-24​

Fixed​

  • documentation typo

7.3.0 - 2025-04-24​

Fixed​

  • unintentional component reset on focus
  • backdrop (along with backdrop color) not available for some placeholder types

Added​

  • added thresholds presets MOBILE and DESKTOP

7.2.1 - 2025-03-24​

Fixed​

  • typescript events types import

7.2.0 - 2025-03-24​

  • Incremental version upgrade

7.1.2 - 2025-03-14​

  • fix typescript import

7.1.1 - 2025-03-13​

Changed​

  • New SAM 1.44.6

7.1.0 - 2025-02-12​

Changed​

  • instruction-changed event now contains the instruction isEscalated property

7.0.1 - 2025-02-05​

Fixed​

  • improved analytics tracking

7.0.0 - 2025-01-08​

Changed​

  • wasmDirectoryPath property to assetsDirectoryPath property. From now, all assets must be placed into dot-asset folder
  • Changed default value of FACE_SHARPNESS_THRESHOLD to 0.25
  • New SAM 1.44.0

Removed​

  • licensePath property. License now has to be placed inside dot-asset folder

6.2.1 - 2024-12-28​

Fixed​

  • Handle Countly crashing

6.2.0 - 2024-11-06​

Added​

  • captureMode property to switch between AUTOCAPTURE and WAIT_FOR_REQUEST capture mode
  • dot-custom-event:request-capture event to trigger capture in WAIT_FOR_REQUEST mode
  • iengine.lic as another default license file name. Now the component will automatically load either iengine.lic or license.lic

Changed​

  • license.lic default license file name flagged as deprecated

Fixed​

  • Custom element prop types

6.1.8 - 2024-10-01​

Fixed​

  • Wrong image in onPhotoTaken callback

6.1.7 - 2024-10-01​

Fixed​

  • Error while switching between cameras on Android devices

6.1.6 - 2024-09-11​

Fixed​

  • Theme customization prop

6.1.5 - 2024-09-02​

Changed​

  • Improved security measures and enhanced protection against vulnerabilities

6.1.4 - 2024-08-21​

Fixed​

  • camera initialization on iOS, when multiple components are used on the same page

6.1.3 - 2024-08-21​

Fixed​

  • unnecessary camera permission request when photo was taken

6.1.2 - 2024-08-07​

Added​

  • ref property to custom HTMLElement type

6.1.1 - 2024-08-01​

  • Incremental version upgrade

6.1.0 - 2024-07-09​

Added​

  • font size, family, weight and style customization

Changed​

  • Update SAM to version 1.39.3
  • Improved detection of face size

6.0.0 - 2024-05-27​

Added​

  • License validation
  • dot_embedded_bg.wasm - WASM binary file for license validation
  • licensePath - path to license file
  • Tiers - freemium/premium mode
  • Freemium overlay component Non-UI components

Changed​

  • Update SAM to version 1.38.1

5.2.8 - 2024-04-10​

Changed​

  • Performance and documentation optimization

5.2.7 - 2024-03-01​

Changed​

  • Performance and documentation optimization

5.2.6 - 2024-02-20​

Changed​

  • Fix typo in package.json

5.2.5 - 2024-02-20​

Changed​

  • Remove type:module from package.json file in order to fix issue with Angular 16

5.2.4 - 2024-02-14​

Fixed​

  • Component not loading in certain conditions on Android in Firefox

5.2.3 - 2023-12-14​

Added​

  • styleTarget property for specifying an alternate DOM node to inject styles. This is useful when rendering components in a shadow DOM. If not specified, the styles are injected into the <head> element of the document.

5.2.2 - 2023-11-27​

Removed​

  • Use of eval() function in third-party library

5.2.1 - 2023-10-18​

Changed​

  • Update SAM to version 1.35.3
  • Improved detection speed
  • Minimum camera resolution validation changed from validating both sides to validating just the shorter side. Now, minimal size of the shorter side is 720px.

5.2.0 - 2023-10-03​

Changed​

  • Update SAM to version 1.35.0
  • Improved detection speed

Added​

  • wasmDirectoryPath - path to directory with Web assembly files.
  • Support for multiple Web assembly files. The component will automatically load the sam.wasm or sam_simd.wasm files from the specified folder, based on the device support of SIMD instructions. Web assembly files have to be placed in wasm folder.

Removed​

  • samWasmUrl - property was removed. Use wasmDirectoryPath property instead.

5.1.0 - 2023-09-28​

Changed​

  • isDeviceTiltWithinBoundsValidator validator for detecting device pitch renamed to isDevicePitchWithinBoundsValidator
  • TILT_ANGLE_THRESHOLD default threshold value renamed toDEVICE_PITCH_ANGLE_THRESHOLD
  • tiltAngleThreshold property for customizing allowed device tilt renamed to devicePitchAngleThreshold

5.0.4 - 2023-09-26​

  • Update content parameter of onPhotoTaken callback

5.0.3 - 2023-09-21​

Changed​

  • Disable SwitchCamera button when component is in candidate_selection phase

5.0.2 - 2023-09-20​

  • Incremental version upgrade

5.0.1 - 2023-08-25​

Fixed​

  • Detector unable to initialize

5.0.0 - 2023-08-17​

Changed​

  • The onPhotoTaken callback change: Image and image data are returned as first parameter. Second parameter is a Record that represents a signed version of the image.
  • Improvements in UI package, new SwitchCamera button icon.
  • Unify thresholds to double-precision floating point format: FACE_SHARPNESS_THRESHOLD, FACE_BRIGHTNESS_LOW_THRESHOLD, FACE_BRIGHTNESS_HIGH_THRESHOLD.
  • Changed default value of MIN_FACE_SIZE_RATIO to 0.16, MAX_FACE_SIZE_RATIO to 0.20, FACE_SHARPNESS_THRESHOLD to 0.3 and FACE_BRIGHTNESS_LOW_THRESHOLD to 0.25.
  • Long instruction text wraps to multiple lines. If text is longer than 34 characters.

Added​

  • Backdrop for the default face placeholder.
  • backdropColor property for changing the color of the default face placeholder backdrop
  • sessionIdForBinaryContent property for generating byte array data
  • isDeviceTiltWithinBoundsValidator validator for detecting device tilt (pitch)
  • TILT_ANGLE_THRESHOLD default threshold value
  • tiltAngleThreshold property for customizing allowed device tilt
  • device_tilted instruction code and appropriate default message

Removed​

  • cameraSettings parameter from onPhotoTaken callback
  • imageType property. Component returns result image in jpeg format.

Fixed​

  • Calculating font size and camera button properties

4.1.6 - 2023-08-14​

  • Security update

4.1.5 - 2023-07-03​

Fixed​

  • declaration files for Typescript version 5 in UI package

4.1.4 - 2023-06-21​

Fixed​

  • declaration files for Typescript version 5

4.1.3 - 2023-05-02​

  • Incremental version upgrade

4.1.2 - 2023-03-31​

  • Incremental version upgrade

4.1.1 - 2023-03-27​

  • Incremental version upgrade

4.1.0 - 2023-03-24​

Changed​

  • Improvements in face detection
  • FACE_BRIGHTNESS_LOW_THRESHOLD lowered from 400 to 300

Fixed​

  • UI component occasionally started in candidate_selection phase after receiving continue-detection event

Changed​

  • detection crop ratio 4:3

Add​

  • Component version in debug layer

4.0.4 - 2023-03-15​

Fixed​

  • Build package in umd format
  • FacePlaceholderIcon changed from enum to union type
  • AppState changed from enum to readonly object

4.0.3 - 2023-03-07​

Fixed​

  • Detection not initialized on slow internet connection. Component remains in "waiting" state
  • "Candidate selection phase" at the beginning of detection when detecting multiple captures
  • applied text-align: center on instruction component on small screen

4.0.2 - 2023-02-23​

Changed​

  • changed instruction when face_not_present

4.0.1 - 2023-01-19​

Fixed​

  • export events from @innovatrics/dot-face-auto-capture/events

4.0.0 - 2023-01-18​

Removed​

  • UI layer from camera component (buttons, placeholder, instruction, app state overlay and detection layer)
  • center face validator
  • FACE_CENTERING_NARROW_SIDE threshold
  • FACE_CENTERING_WIDE_SIDE threshold

Added​

  • UI package with placeholder, instructions, buttons and detection layer
  • Custom events and events listeners for communication from app to component (switch-camera, toggle-mirror)
  • Custom events and events listeners for communication from components to app (camera-resolution-changed, instruction-changed, detected-document-changed, state-changed)
  • detection layer with detected face circle
  • showDetectionLayer switch for show/hide camera buttons (switch camera, toggle mirror)
  • showCameraButtons switch for show/hide detection layer
  • OutOfBounds validator
  • outOfBoundsValidationRectangle
  • outOfBoundsDetectionPoints
  • all rectangles and points into debug layer
  • SAM version into debug layer

Changed​

  • Rename photoTakenCb to onPhotoTaken
  • Order of instruction processing. Before validating the centering of the detected face, the size of the detected face is validated.
  • Component is now build as umd and es module
  • Camera buttons (switch camera, toggle mirror) are now hidden by default

3.5.2 - 2022-12-16​

Fixed​

  • Camera switch on Android devices with Firefox

3.5.1 - 2022-10-13​

Fixed​

  • Memoized props from first instance which holds reference to callback function from initialization on every capture

3.5.0 - 2022-10-10​

Changed​

  • Best candidate selection by sharpness
  • Dynamic candidate selection phase duration
  • Center face narrow side validator from 0.07 to 0.12

Fixed​

  • Minimal camera resolution check
  • Selection of best image in candidate selection phase entering

Removed​

  • Hotspots validator with hotspotsMediumThreshold and number hotspotsHighThreshold

3.4.3 - 2022-09-28​

Fixed​

  • Possible false candidate selection on first frame after entering candidate selection

3.4.2 - 2022-08-10​

Fixed​

  • Typescript declaration files export

3.4.1 - 2022-08-09​

Fixed​

  • Typescript declaration files export

Change​

  • Dependencies update and upgrade

3.3.1 - 2022-07-04​

Fixed​

  • Zero height of component when error occurs

Add​

  • add appStateInstructions property to uiCustomisation
  • add option to change appState instructions text and visibility

Change​

  • interface for changing Loading appState instruction text

3.3.0 - 2022-06-03​

Added​

  • Add support for capturing multiple face photos
  • Add custom event face-auto-capture with continue-detection instruction to continue detection

Changed​

  • When photoTakenCb is called, component switches into waiting state
  • Parent of <x-dot-face-auto-capture /> does not have to have a defined height

3.2.0 - 2022-05-23​

Added​

  • Add Countly analytics tracking
  • Add image parameters (brightness, sharpness, hotspot)
  • Session recording for face detection

Changed​

  • onError callback returns AutoCaptureError
  • onError callback is required
  • Show error screen when error occurs

Fixed​

  • Stucked component when error occurs

3.1.2 - 2022-04-04​

Changed​

  • Remove force manual capture on instruction click

3.1.1 - 2022-03-15​

Changed​

  • Change optimalFaceSizeLimit and optimalFaceSizeParam to minFaceSizeRatio and maxFaceSizeRatio
  • Change faceCenterLimit to faceCenteringNarrowSide and faceCenteringWideSide
  • Set minFaceSizeRatio default value to 0.35 and maxFaceSizeRatio to 0.44
  • Set faceCenteringNarrowSide default value to 0.07 and faceCenteringWideSide to 0.21

3.1.0 - 2022-02-03​

Fixed​

  • Unify loading and instruction design

3.0.2 - 2022-01-28​

Added​

  • Add loading screen
  • Add loading.text property in uiCustomisation for configuring text on loading screen

Changed​

  • Show new instruction only if 600ms elapsed since last instruction change

3.0.1 - 2022-01-25​

Added​

  • file sam.wasm

Fixed​

  • safari version 15 on mac

Changed​

  • Face detection accuracy improved.
  • Detection engine

Removed​

  • blaze_models package
  • modelUrls option from cameraOptions

2.3.1 - 2022-01-10​

Fixed​

  • Fix bug causing integration error

2.3.0 - 2022-01-05​

Added​

  • add cameraSettings into photoTakenCb callBack function
  • Redesign of the UI of Face Auto Capture component.

Changed​

  • photoTakenCb callBack function structure

2.2.2 - 2021-12-17​

  • Incremental version upgrade

2.2.1 - 2021-12-09​

Changed​

  • Hide switch camera button if there is only 1 webcam available

2.2.0 - 2021-11-30​

Added​

  • thresholds.faceConfidence - Detection confidence threshold with default value 0.12
  • modelUrls - Object with path to the models needed for detection

Changed​

  • integrated new neural network for face detection
  • dynamic import of TensorFlow.js libraries

2.1.0 - 2021-11-18​

  • First released version