DOT Web MagnifEye Liveness
v4.1.1
Introduction
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.
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)
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
.
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.
Important Notice
For security reasons, the use of devtools is not possible with DOT Web MagnifEye Liveness.
Non-ui component
Requirements
Minimum required camera resolution for appropriate results is 720p. Anything less than 720p 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: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 props
needs to be passed into component after <x-dot-magnifeye-liveness />
tag was rendered.
import type {
MagnifEyeLivenessProps,
HTMLMagnifEyeLivenessElement
} from "@innovatrics/dot-magnifeye-liveness";
import { useEffect, useCallback } from "react";
import "@innovatrics/dot-magnifeye-liveness";
const MagnifEyeLiveness = (props: MagnifEyeLivenessProps) => {
useEffect(() => {
const magnifEyeHTMLElement = document.getElementById(
"x-dot-magnifeye-liveness"
) as HTMLMagnifEyeLivenessElement | null;
if (magnifEyeHTMLElement) {
magnifEyeHTMLElement.props = props;
}
});
return <x-dot-magnifeye-liveness id="x-dot-magnifeye-liveness" />;
};
const Page = () => {
const handleOnComplete = (data: OnCompleteData, content: Uint8Array) => {
// ...
};
// Save function reference to prevent unnecessary reload of component
const handleError = useCallback(
(error: Error) => {
alert(error)
},
[],
);
return (
<MagnifEyeLiveness
onComplete={handleOnComplete}
onError={handleError}
/>
);
};
See also DOT Web Samples showing the usage of DOT Web Auto Capture components in different front-end technologies like React, Angular…
TypeScript
Declaration file is bundled inside package. To use with TypeScript, import types from @innovatrics/dot-magnifeye-liveness
.
import type { MagnifEyeLivenessCallback, MagnifEyeLivenessProps } from "@innovatrics/dot-magnifeye-liveness";
Hosting SAM wasm
The component needs to have access to the WebAssembly wasm binary file. It’s distributed in the package, and needs to be hosted by the website provider.
By default, component try to fetch wasm file from <PROJECT_ORIGIN>/sam.wasm
. This can be changed using the samWasmUrl
property.
If using Create React App
, copy the`sam.wasm` file to public
folder. In our example the final path is public/sam.wasm
.
Properties
function onComplete
- Callback on successful image capture(data: OnCompleteData, content: Uint8Array) ⇒ void
see Callback parameters
function onError
– Callback in the case that an error occurred (see Handling errors)(e: Error) ⇒ void
(Optional)
string samWasmUrl
- URL link to the location where the wasm binary file is hosted
Callback parameters
object data
Blob image
– Returned image on successful captureobject data
(Optional) object cameraSettings
- MediaTrackSettings object containing used webcam settings. The object in addition contains device name.(Optional) object detection
- Object contains all detection parameters and its values. Present if image was taken using auto capture (not manual capture).(Optional) 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'}}>
<MagnifEyeLiveness
onComplete={handleOnComplete}
onError={handleOnError}
/>
<MagnifEyeLivenessUi showCameraButtons/>
</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: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 props
needs to be passed into component after <x-dot-magnifeye-liveness-ui />
tag was rendered.
import type {
MagnifEyeLivenessUiProps,
HTMLMagnifEyeLivenessUiElement
} from '@innovatrics/dot-autocapture-ui/magnifeye-liveness';
import { useEffect } from 'react';
import "@innovatrics/dot-auto-capture-ui/magnifeye-liveness";
const MagnifEyeLivenessUi = (props: MagnifEyeLivenessUiProps) => {
useEffect(() => {
const uiElement = document.getElementById(
"x-dot-magnifeye-auto-capture-ui"
) as HTMLMagnifEyeLivenessUiElement | null;
if (uiElement) {
uiElement.props = props;
}
});
return <x-dot-magnifeye-auto-capture-ui id="x-dot-magnifeye-auto-capture-ui" />;
};
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)
['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']
fit_your_eye
- Shown in last phase when user should move closer to camera and fit eye into square.
(Optional)
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)
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)
[false]
boolean
showCameraButtons
- Show/hide camera buttons (switch camera and toggle mirror) on top of component
Example how to use UI properties:
<MagnifEyeLivenessUi
theme={{ colors: { placeholderColor: 'green' } }}
instructions={{ candidate_selection: 'Candidate selection' }}
appStateInstructions={{ loading: { text: 'Component is loading', visible: true } }}
showCameraButtons
/>
Example of using components together
import type { OnCompleteData } from '@innovatrics/dot-magnifeye-liveness';
import { useCallback } from 'react';
import MagnifEyeLivenessUi from './MagnifEyeLivenessUi';
import MagnifEyeLiveness from './MagnifEyeLiveness'
const MagnifEye = () => {
const handleOnComplete = (data: OnCompleteData, content: Uint8Array) => {
console.log(data.data, data.image)
};
const handleOnError = useCallback(
(error: Error) => {
alert(error)
},[]);
return (
<div style={{ position: 'relative', overflow: 'hidden' }}>
<MagnifEyeLiveness
onComplete={handleOnComplete}
onError={handleOnError}
/>
<MagnifEyeLivenessUi showCameraButtons />
</div>
);
};