DOT Web MagnifEye Liveness
v8.0.3
Introduction
| MagnifEye Liveness component is deprecated and will be discontinued in the next major release. Please migrate to Multi-Range Liveness component. |
DOT Web MagnifEye Liveness is set of Non-ui component and Ui component web components providing a semi-passive liveness capture. Components navigate user to capture a detailed image of the eye and lays foundations for the multimodal capability of liveness detection. The process can be performed within seconds and does not compromise the customer experience.
Non-ui component is a web component that renders the video stream from an available phone or web camera to automatically capture images of a user’s face with the required quality. The component uses an enhanced candidate selection process to ensure optimal image quality.
Ui component is a web component that renders an overlay over video stream. Overlay includes a placeholders, camera control buttons and instructions to guide the user to position their face correctly.
Both components should always be used together, unlike DOT Web Document Auto Capture or DOT Web Face Auto Capture, MagnifEye Liveness Ui component can not be custom implemented.
Supported Browsers
DOT Web MagnifEye Liveness 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:
* 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.
** 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 MagnifEye Liveness in WKWebView on iPhone or iPad, allowsInlineMediaPlayback and mediaTypesRequiringUserActionForPlayback properties on WKWebViewConfiguration must be set to true.
**** @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 MDN docs.
Non-ui component
Requirements
Minimum required camera resolution for appropriate results is 720x720. Anything less is insufficient.
Initialization
DOT Web MagnifEye Liveness can be installed via NPM, yarn or pnpm
npm install @innovatrics/dot-magnifeye-liveness
To manually integrate the DOT Web MagnifEye Liveness, download latest version from the Github repository. Then add following line to dependencies in your package.json:
"dependencies": {
"@innovatrics/dot-magnifeye-liveness": "file:innovatrics-dot-magnifeye-liveness-[VERSION].tgz"
},where [VERSION] is the DOT Web MagnifEye Liveness version integrated. This installs dot-magnifeye-liveness 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-magnifeye-liveness'; in the app.
Usage
MagnifEye Liveness component is a web component which uses custom HTML <x-dot-magnifeye-liveness /> tag.
Properties configuration needs to be passed into component after <x-dot-magnifeye-liveness /> tag was rendered.
import type {
MagnifEyeLivenessConfiguration,
HTMLMagnifEyeLivenessElement,
OnCompleteData
} from "@innovatrics/dot-magnifeye-liveness";
import { useEffect } from "react";
import "@innovatrics/dot-magnifeye-liveness";
function MagnifEyeLiveness(configuration: MagnifEyeLivenessConfiguration) {
useEffect(() => {
const magnifEyeHTMLElement = document.getElementById(
"x-dot-magnifeye-liveness"
) as HTMLMagnifEyeLivenessElement | null;
if (magnifEyeHTMLElement) {
magnifEyeHTMLElement.configuration = configuration;
}
});
return <x-dot-magnifeye-liveness id="x-dot-magnifeye-liveness" />;
}
function Page() {
function handleOnComplete(data: OnCompleteData, content: Uint8Array) {
// ...
}
function handleError(error: Error) {
alert(error);
}
return (
<MagnifEyeLiveness
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 {
MagnifEyeLivenessConfiguration,
HTMLMagnifEyeLivenessElement
} from "@innovatrics/dot-magnifeye-liveness";
import { useLayoutEffect, useRef } from "react";
import "@innovatrics/dot-magnifeye-liveness";
function MagnifEyeLiveness(configuration: MagnifEyeLivenessConfiguration) {
const ref = useRef<HTMLMagnifEyeLivenessElement | null>(null);
useLayoutEffect(() => {
const element = ref.current;
if (element) {
element.configuration = configuration;
}
}, [configuration]);
return <x-dot-magnifeye-liveness id="x-dot-magnifeye-liveness" 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 MagnifEye Liveness. 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 MagnifEye Liveness 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 article.
TypeScript
Declaration file is bundled inside package. To use with TypeScript, import types from @innovatrics/dot-magnifeye-liveness.
import type { MagnifEyeLivenessCallback, MagnifEyeLivenessConfiguration } from "@innovatrics/dot-magnifeye-liveness";Multi capture
MagnifEye Liveness component allows you to capture an unlimited number of MagnifEye sequences without the need to reinitialize the webcam and detector.
Component calls onComplete callback on every captured MagnifEye sequence. When onComplete is called, detection is paused. Camera stream and face detector stay initialized.
Component is in waiting state. You can "restart" detection by calling MagnifEyeCustomEvent.CONTROL with ControlEventInstruction.CONTINUE_DETECTION instruction. See Control Events section for more details.
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:
copy
dot-assetsdirectory from our distribution into your distribution every time you update to new version of the component. If you are using package manager, you can finddot-assetsdirectory innode_modules/@innovatrics/dot-magnifeye-liveness/dot-assets.copy
iengine.lic(orlicense.lic) file intodot-assetsfolder in your distribution.
Please note that dot-assets files need to be hosted at the same URL as your app - 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-magnifeye-liveness/
|__ dot-assets/ <-- copy this directory
|__ magnifeye/
|__ wasm/
|-- sam.wasm
|-- sam_simd.wasm
|-- dot-<CHUNK_HASH>.js
...
|__ wasm/
|-- dot_embedded_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)
|__ magnifeye/
|__ 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/
|-- dot_embedded_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 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. magnifeye 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)
|__ magnifeye/ <-- copied from @innovatrics/dot-magnifeye-liveness
|__ 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:

Premium
To run components in premium mode, dot_embedded_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].
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.
* 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
(Optional)
object camera- Camera configuration(Optional)
[false]boolean isVideoCaptureEnabled– Enables video capture feature. Works only with DOT Digital Identity Service. When enabled, component captures the last 8 seconds of the camera stream before the moment of capture. Check Supported Browsers for details about the limitations regarding browser support. The captured video is bundled into the component’s result binary content and can be retrieved via the Digital Identity Service (DIS) for the purposes of Identity proofing.(Optional)
['user']string facingMode– Defines which camera to acquire from the browser’s getUserMedia API'user'– The video source is facing toward the user; this is the selfie or front-facing camera on a smartphone'environment'– The video source is facing away from the user, thereby viewing their environment; this is the back camera on a smartphone
function onComplete- Callback on successful image capture(data: OnCompleteData, content: Uint8Array) ⇒ voidsee Callback parameters
function onError– Callback in the case that an error occurred (see Handling errors)(e: Error) ⇒ void
(Optional)
string sessionToken– Unique identifier of the session(Optional)
string transactionCountingToken– Unique identifier for the transaction counting feature(Optional)
string assetsDirectoryPath- Path to thedot-assetsdirectory(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.
Callback parameters
object dataBlob image– Returned image on successful captureobject dataobject detection- Object contains all detection parameters and its values. Present if image was taken using auto capture (not manual capture).object imageResolution- Width and height of the captured image.
Uint8Array content- output for DOT Digital Identity Service
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 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
Requirements
Both components must be wrapped in parent div with position: relative and overflow: hidden.
<div style={{position: "relative", overflow: "hidden"}}>
<MagnifEyeLivenessUi control={{ showCameraButtons: true }} />
<MagnifEyeLiveness
onComplete={handleOnComplete}
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 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 MagnifEye Liveness 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
Magnifeye Liveness UI component is an web component which uses custom HTML <x-dot-magnifeye-liveness-ui /> tag.
Properties configuration needs to be passed into component after <x-dot-magnifeye-liveness-ui /> tag was rendered.
import type {
MagnifEyeLivenessUiConfiguration,
HTMLMagnifEyeLivenessUiElement
} from "@innovatrics/dot-auto-capture-ui/magnifeye-liveness";
import { useEffect } from "react";
import "@innovatrics/dot-auto-capture-ui/magnifeye-liveness";
function MagnifEyeLivenessUi(configuration: MagnifEyeLivenessUiConfiguration) {
useEffect(() => {
const uiElement = document.getElementById(
"x-dot-magnifeye-liveness-ui"
) as HTMLMagnifEyeLivenessUiElement | null;
if (uiElement) {
uiElement.configuration = configuration;
}
});
return <x-dot-magnifeye-liveness-ui id="x-dot-magnifeye-liveness-ui" />;
}Alternatively, you can use useRef and useLayoutEffect to render a web component with its props.
import type {
MagnifEyeLivenessUiConfiguration,
HTMLMagnifEyeLivenessUiElement
} from "@innovatrics/dot-auto-capture-ui/magnifeye-liveness";
import { useLayoutEffect, useRef } from "react";
import "@innovatrics/dot-auto-capture-ui/magnifeye-liveness";
function MagnifEyeLivenessUi(configuration: MagnifEyeLivenessUiConfiguration) {
const ref = useRef<HTMLMagnifEyeLivenessUiElement | null>(null);
useLayoutEffect(() => {
const element = ref.current;
if (element) {
element.configuration = configuration;
}
}, [configuration]);
return <x-dot-magnifeye-liveness-ui id="x-dot-magnifeye-liveness-ui" ref={ref} />
}TypeScript
Declaration files are bundled inside package. Just import types from @innovatrics/dot-autocapture-ui/magnifeye-liveness.
Properties
(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(Optional)
['Position your face into the circle']string right_eye_not_present- Shown when right eye is not detected(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)
['Fit your eye into square']string fit_your_eye- Shown in last phase when user should move closer to camera and fit eye into square(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 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)
done- Component finished capturing image(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]booleanshowCameraButtons- 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:
<MagnifEyeLivenessUi
styling={{
theme: { colors: { placeholderColor: "green" }, font: { style: 'italic' } },
backdropColor: "rgba(10, 10, 10, 0.5)"
}}
control={{ 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>Example of using components together
import type { OnCompleteData } from "@innovatrics/dot-magnifeye-liveness;
import MagnifEyeLivenessUi from "./MagnifEyeLivenessUi";
import MagnifEyeLiveness from "./MagnifEyeLiveness";
function MagnifEye() {
function handleOnComplete(data: OnCompleteData, content: Uint8Array) {
console.log(data.data, data.image)
}
function handleError(error: Error) {
alert(error);
}
return (
<div style={{ position: "relative", overflow: "hidden" }}>
<MagnifEyeLivenessUi control={{ showCameraButtons: true }} />
<MagnifEyeLiveness
onComplete={handleOnComplete}
onError={handleError}
transactionCountingToken="provide-the-token-here"
/>
</div>
);
}Example how to use styleTarget prop with Ui component when using Shadow DOM:
This approach also works for Non-ui component.
import type {
MagnifEyeLivenessUiConfiguration,
HTMLMagnifEyeLivenessUiElement
} from "@innovatrics/dot-auto-capture-ui/magnifeye-liveness";
import { useEffect } from "react";
import "@innovatrics/dot-auto-capture-ui/magnifeye-liveness";
function MagnifEyeLivenessUi(configuration: MagnifEyeLivenessUiConfiguration) {
useEffect(() => {
const uiElement = document.getElementById(
"x-dot-magnifeye-liveness-ui"
) as HTMLMagnifEyeLivenessUiElement | null;
const styleNode = document.createElement('div');
uiElement?.shadowRoot?.append(styleNode);
if (uiElement) {
uiElement.configuration = {
...configuration,
styleTarget: styleNode,
};
}
});
return <x-dot-magnifeye-liveness-ui id="x-dot-magnifeye-liveness-ui" />;
}HTML of example above will look like this:
<x-dot-magnifeye-liveness-ui id="x-dot-magnifeye-liveness-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-magnifeye-liveness-ui>Custom Events - Optional
Communication between components is based on custom events. Ui component is mostly listening to events dispatched by Non-ui component.
Type of Events
Currently most of the events used are described in this section. You can create custom UI parts using these events.
enum MagnifEyeCustomEvent- Event names dispatched by componentsSTATUS_CHANGED = 'magnifeye-auto-capture:status-changed'- Notifies UI when state or phase of Non-ui component has changedCONTROL = 'magnifeye-auto-capture:control'- Events dispatched to controluiandnon-uicomponents.
Usage
Import '@innovatrics/dot-magnifeye-liveness/ui-common/src/types' to use event types.
Listening to the Events
All event listeners are already implemented in default Ui component. Skip this section if you are using default Ui component.
All documented MagnifEyeCustomEvent events are dispatched by Non-ui component. Ui component listens to these events to make appropriate changes. See the example below how to register event listeners.
import type { AutoCaptureError } from '@innovatrics/dot-magnifeye-liveness/ui-common/src/error';
import type { MagnifEyeState, MagnifEyePhase } from '@innovatrics/dot-magnifeye-liveness/ui-common/src/types';
import { MagnifEyeCustomEvent} from '@innovatrics/dot-magnifeye-liveness/ui-common/src/types';
import { useEffect, useState } from 'react';
export function Events() {
const [magnifEyePhase, setMagnifEyePhase] = useState<MagnifEyePhase | undefined>();
const [magnifEyeState, setMagnifEyeState] = useState<MagnifEyeState | undefined>();
const [magnifEyeError, setMagnifEyeError] = useState<AutoCaptureError>();
useEffect(() => {
function handleStatusChanged(event: MagnifEyeCustomEvent) {
const { error, state, phase } = event.detail || {};
if (phase) {
setMagnifEyePhase(phase);
}
if (state) {
setMagnifEyeState(state);
}
if (error) {
setMagnifEyeError(error);
}
}
document.addEventListener(MagnifEyeCustomEvent.STATUS_CHANGED, handleStatusChanged);
return () => {
document.removeEventListener(MagnifEyeCustomEvent.STATUS_CHANGED, handleStatusChanged);
};
}, []);
};Without importing @innovatrics/dot-magnifeye-liveness/ui-common/src/types you can use values of MagnifEyeCustomEvent directly.
const statusChangeEvent = "magnifeye-auto-capture:status-changed";
function handleStatusChange(event) {
console.log(event.detail.state)
console.log(event.detail.phase)
}
document.addEventListener(statusChangeEvent, handleStatusChange);
/**
* remove event listener when you're done
*/
document.removeEventListener(statusChangeEvent, handleStatusChange);Control Events
Control events are dispatched from outside of Non-ui component to control it.
MagnifEyeCustomEvent.CONTROL
Events are dispatched from Ui component to control Non-ui component.
enum ControlEventInstructionCONTINUE_DETECTION = 'continue-detection'- Controls Multi capture
import { dispatchControlEvent, MagnifEyeCustomEvent, ControlEventInstruction } from "@innovatrics/dot-magnifeye-liveness/events";
export function Dispatch() {
function continueDetection() {
dispatchControlEvent(MagnifEyeCustomEvent.CONTROL, ControlEventInstruction.CONTINUE_DETECTION)
}
return (
<div>
<button onClick={continueDetection}>Continue detection</button>
</div>
)
}Without importing @innovatrics/dot-magnifeye-liveness/events you can use values of MagnifEyeCustomEvent and ControlEventInstruction directly.
function continueDetection() {
document.dispatchEvent(
new CustomEvent("magnifeye-auto-capture:control", {
detail: { instruction: "continue-detection" },
}),
);
}Code Samples
See also DOT Web Samples showing the usage of DOT Web Auto Capture components in different front-end technologies like React, Angular…
Appendix
Changelog
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
propsrenamed toconfigurationNon-UI component:
HTMLMagnifEyeLivenessElement.propsrenamed toHTMLMagnifEyeLivenessElement.configurationNon-UI component:
MagnifEyeLivenessPropstype renamed toMagnifEyeLivenessConfigurationUI component: property
propsrenamed toconfigurationUI component:
HTMLMagnifEyeLivenessUiElement.propsrenamed toHTMLMagnifEyeLivenessUiElement.configurationUI component:
MagnifEyeLivenessUiPropstype renamed toMagnifEyeLivenessUiConfigurationUI component:
showCameraButtonsmoved to nestedcontrolobject (control.showCameraButtons)UI component:
backdropColormoved to nestedstylingobject (styling.backdropColor)UI component:
thememoved to nestedstylingobject (styling.theme)Changed default analytics provider from Countly to Innovatrics Metrics Middleware
BREAKING CHANGE Transaction reporting is now enabled by default (
transactionCountingTokenrequired in initialization phase when transaction reporting is included in license) (breaking change)
Deprecated
MagnifEye Liveness component is deprecated and will be discontinued in the next major release. Please migrate to Multi-Range Liveness component. A warning message will be displayed on localhost when using this component.
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)
isVideoCaptureEnabledto enable Video Capture
Changed
update
SAMto version 1.50.5
7.6.1 - 2025-10-17
Fixed
Issue preventing capture from finishing
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
transactionCountingTokenproperty to provide token for transaction reportingTransaction reporting (for licenses with enabled transaction reporting)
Fixed
Improved data integrity and stability fixes
Changed
update
SAMto version 1.50.2
7.4.0 - 2025-07-09
Changed
default candidate selection duration changed to 2000ms
update
SAMto version 1.49.1component resets when face has been lost
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.1 - 2025-04-24
Fixed
documentation typo
7.3.0 - 2025-04-24
Fixed
unintentional component reset on focus
Added
documentation for
STATUS_CHANGEDeventcontrol event
CONTINUE_DETECTIONadded thresholds presets
MOBILEandDESKTOP
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-changedevent now contains the instructionisEscalatedproperty
7.0.1 - 2025-02-05
Fixed
improved analytics tracking
7.0.0 - 2025-01-08
Changed
wasmDirectoryPathproperty toassetsDirectoryPathproperty. From now, all assets must be placed intodot-assetfolderNew SAM 1.44.0
Removed
licensePathproperty. License now has to be placed insidedot-assetfolder
6.2.0 - 2024-11-06
Added
iengine.licas another default license file name. Now the component will automatically load eitheriengine.licorlicense.lic
Changed
license.licdefault license file name flagged as deprecated
Fixed
Custom element prop types
6.1.8 - 2024-10-01
Fixed
Wrong image in
onPhotoTakencallback
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
refproperty 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
SAMto version 1.39.3Improved detection of face size
6.0.0 - 2024-05-27
Added
License validation
dot_embedded_bg.wasm- WASM binary file for license validationlicensePath- path to license fileTiers - freemium/premium mode
Freemium overlay component Non-UI components
Changed
Update
SAMto version 1.38.1Fix overwriting of middle image by last one
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:modulefrompackage.jsonfile 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
styleTargetproperty 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
Fixed
Placeholder backdrop stroke width
5.2.1 - 2023-10-18
Changed
Update
SAMto version 1.35.3Improved 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
SAMto version 1.35.0Improved detection speed
Added
wasmDirectoryPath- path to directory with Web assembly files.Support for multiple Web assembly files. The component will automatically load the
sam.wasmorsam_simd.wasmfiles from the specified folder, based on the device support of SIMD instructions. Web assembly files have to be placed inwasmfolder.
Removed
samWasmUrl- property was removed. UsewasmDirectoryPathproperty instead.
5.1.0 - 2023-09-28
Changed
isDeviceTiltWithinBoundsValidatorvalidator for detecting device pitch renamed toisDevicePitchWithinBoundsValidatorTILT_ANGLE_THRESHOLDdefault threshold value renamed to`DEVICE_PITCH_ANGLE_THRESHOLD`tiltAngleThresholdproperty for customizing allowed device tilt renamed todevicePitchAngleThreshold
5.0.4 - 2023-09-26
Update
contentparameter ofonCompletecallback
5.0.3 - 2023-09-21
Changed
Disable
SwitchCamerabutton when component is incandidate_selectionphase
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
Improvements in UI package, new
SwitchCamerabutton icon.Long instruction text wraps to multiple lines. If text is longer than 34 characters.
Added
Countlyanalytics trackingBackdrop for the placeholder.
backdropColorprop for changing the color of the placeholder backdropsessionIdForBinaryContentproperty
Fixed
MagnifEye instruction position fixed
Occasionally canceling animation, when user moved too fast
Calculating font size and camera button properties
MagnifEye zoom
Removed
cameraSettingsparameter fromonPhotoTakencallback
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
Fixed
Occasional
unknown camera errorwhen using MagnifEye Liveness component and Face Auto Capture component in one application
4.1.2 - 2023-03-31
MagnifEye Liveness improvements
4.1.1 - 2023-03-27
Fixed
Type declaration files
4.1.0 - 2023-03-24
First released version