DOT Web Face Auto Capture Migration

This guide describes how to migrate DOT Web Face Auto Capture component from version 3 to version 4.

Introduction#

Web Face Auto Capture component is now separated from its UI layer, divided in ui and non-ui part. Each part is represented as individual web component. You can download ui package from npm and customize it the same way as before. It is also possible to create the whole UI by yourself and just use the auto capture logic from non-ui component.

Migration Steps#

Initialization#

Update Face Auto Capture package to version 4.0.0.

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

Install UI package. This step is optional, you can create your own UI layer.

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

Usage#

non-ui component can be used the same way as before. Usage of ui component is similar to non-ui.

Example of non-ui component, same as before:

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

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

    if (faceAutoCaptureHTMLElement) {
      faceAutoCaptureHTMLElement.cameraOptions = props;
    }
  });

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

Example of ui component:

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

const FaceUi = (props: FaceUiProps) => {
  useEffect(() => {
    const uiElement = document.getElementById('x-dot-face-auto-capture-ui') as HTMLFaceUiElement | null;

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

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

export default FaceUi;

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

<div style={{position: 'relative'}}>
  <FaceCamera
    imageType="png"
    cameraFacing="user"
    onPhotoTaken={handlePhotoTaken}
    onError={onError}
  />
  <FaceUi />
</div>

Changes#

All changes are described in this section. See comparison with previous version in code example.

non-ui Component Properties#

onPhotoTakenCb#

Property was renamed to onPhotoTaken.

uiCustomisation#

Property was removed.

In previous version UI layer could be customized via uiCustomisation object.

Now you need to pass those properties directly as props to UI package, without wrapping them in uiCustomisation object.

export type FaceUiProps = {
  theme?: DeepPartial<AutoCaptureTheme>;
  appStateInstructions?: AppStateInstructions;
  instructions?: Partial<FaceInstructions>;
  placeholder?: FacePlaceholderIcon;
  showDetectionLayer?: boolean;
  showCameraButtons?: boolean;
};

ui Component Properties#

instructions#

Change of internal type. You can use this property the same was as before.

export type FaceInstructionCode =
  | 'candidate_selection'
  | 'face_too_close'
  | 'face_too_far'
  | 'face_centering'
  | 'face_not_present'
  | 'sharpness_too_low'
  | 'brightness_too_low'
  | 'brightness_too_high';

export type FaceInstructions = Record<FaceInstructionCode, string>;

appStateInstructions#

Without change.

placeholder#

Type of placeholder was change to FacePlaceholderIcon.

export enum FacePlaceholderIcon {
  CIRCLE_SOLID = 'circle-solid',
  ELLIPSE_SOLID = 'ellipse-solid',
  MAN_SOLID = 'man-solid',
  WOMAN_SOLID = 'woman-solid',
  SQUARE_ROUNDED_DASH = 'square-rounded-dash',
  SQUARE_ROUNDED_SOLID = 'square-rounded-solid',
  SQUARE_DASH = 'square-dash',
  SQUARE_SOLID = 'square-solid',
}

theme#

Previously you could customize colors via colors prop. Now colors is property of theme.

export type AutoCaptureTheme = {
  colors: {
    placeholderColor: string;
    placeholderColorSuccess: string;
    instructionColor: string;
    instructionColorSuccess: string;
    instructionTextColor: string;
  };
};

showDetectionLayer - new property#

Renders border around detected face in real time when confidence is above threshold.

Default value is false.

showCameraButtons - new property#

Display camera buttons (mirror camera stream, switch camera).

Default values is false.

Example#

Previous version:

<FaceCamera
  imageType="png"
  cameraFacing="user"
  photoTakenCb={handlePhotoTaken}
  onError={onError}
  samWasmUrl="/sam.wasm"
  uiCustomisation={{
    placeholder: {
      facePlaceholder: 'ellipse-solid',
    },
    instructions: {
      candidate_selection: 'Candidate selection',
    },
    appStateInstructions: {
      loading: { text: 'Component is loading' },
      waiting: { visible: false }
    },
    colors: {
      placeholderColor: 'green',
    }
  }}
/>

import { FacePlaceholderIcon } from '@innovatrics/dot-auto-capture-ui/face';

<div style={{position: 'relative'}}>
  <FaceCamera
    imageType="png"
    cameraFacing="user"
    photoTakenCb={handlePhotoTaken}
    onError={onError}
    samWasmUrl="/sam.wasm"
  />
  <FaceUi
    showCameraButtons
    placeholder={FacePlaceholderIcon.ELLIPSE_SOLID}
    instructions={{ candidate_selection: 'Candidate selection' }}
    appStateInstructions={{
      loading: { text: 'Component is loading'},
      waiting: { visible: false },
    }}
    theme={{ colors: { placeholderColor: 'green' } }}
  />
</div>

Eventually in javascript use value of FacePlaceholderIcon.

<FaceUi placeholder="ellipse-solid" />

Code Samples#

See also code samples showing the usage of DOT Web Auto Capture components in different front-end technologies.