DOT Web Document Auto Capture Migration

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

Introduction

Web Document Auto Capture component is now separated from its UI layer, divided into ui and non-ui part. Each part is represented as an 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 Document Auto Capture package to version 4.0.0.

npm install @innovatrics/dot-document-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 { DocumentCameraProps, HTMLDocumentCaptureElement } from '@innovatrics/dot-document-auto-capture';
import '@innovatrics/dot-document-auto-capture';

const DocumentCamera = (props: DocumentCameraProps) => {
  useEffect(() => {
    const documentAutoCaptureHTMLElement = document.getElementById(
      'x-dot-document-auto-capture'
    ) as HTMLDocumentCaptureElement | null;

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

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

Example of ui component:

import '@innovatrics/dot-auto-capture-ui/document'
import type { DocumentUiProps, HTMLDocumentUiElement } from '@innovatrics/dot-auto-capture-ui/document';
import { useEffect } from 'react';

const DocumentUi = (props: DocumentUiProps) => {
  useEffect(() => {
    const uiElement = document.getElementById('x-dot-document-auto-capture-ui') as HTMLDocumentUiElement | null;

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

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

export default DocumentUi;

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

<div style={{position: 'relative'}}>
  <DocumentCamera
    imageType="png"
    cameraFacing="environment"
    onPhotoTaken={handlePhotoTaken}
    onError={onError}
  />
  <DocumentUi />
</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.

displayDetectionLayer

Property was renamed to showDetectionLayer and moved to ui component.

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 DocumentUiProps = {
  theme?: DeepPartial<AutoCaptureTheme>;
  appStateInstructions?: AppStateInstructions;
  instructions?: Partial<DocumentInstructions>;
  placeholder?: DocumentPlaceholderIcon;
  showDetectionLayer?: boolean;
  showCameraButtons?: boolean;
};

ui Component Properties

instructions

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

export type DocumentInstructionCode =
  | 'candidate_selection'
  | 'document_centering'
  | 'document_too_close'
  | 'document_not_present'
  | 'document_too_far'
  | 'sharpness_too_low'
  | 'brightness_too_low'
  | 'brightness_too_high'
  | 'hotspots_present';

export type DocumentInstructions = Record<DocumentInstructionCode, string>;
appStateInstructions

Without change.

placeholder

Type of placeholder was changed to DocumentPlaceholderIcon.

export enum DocumentPlaceholderIcon {
  ID_CORNERS = 'id-corners',
  ID_DASH = 'id-dash',
  ID_DOT = 'id-dot',
  ID_SOLID = 'id-solid',
  ID_PHOTO_ROUNDED = 'id-photo-rounded',
  ID_CORNERS_ROUNDED = 'id-corners-rounded',
  ID_DASH_ROUNDED = 'id-dash-rounded',
  ID_DOT_ROUNDED = 'id-dot-rounded',
  ID_SOLID_ROUNDED_BACK = 'id-solid-rounded-back',
  ID_SOLID_ROUNDED = 'id-solid-rounded',
  PASSPORT_SOLID_BACK = 'passport-solid-back',
  PASSPORT_SOLID_BACK_BLANK = 'passport-solid-back-blank',
}
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

Boolean value to determine if detection layer should be visible.

showCameraButtons - new property

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

Default value is false.

Example

Previous version:

 <DocumentCamera
  imageType="png"
  cameraFacing="environment"
  onPhotoTaken={handlePhotoTaken}
  onError={onError}
  samWasmUrl="/sam.wasm"
  isDetectionLayerVisible={false}
  uiCustomisation={{
    placeholder: {
      documentPlaceholder: 'id-rectangle-corners-front',
    },
    instructions: {
      candidate_selection: 'Candidate selection',
    },
    appStateInstructions: {
      loading: { text: 'Component is loading' },
      waiting: { visible: false }
    },
    colors: {
      placeholderColor: 'green',
    }
  }}
/>

After migration:

import { DocumentPlaceholderIcon } from '@innovatrics/dot-auto-capture-ui/document';

<div style={{position: 'relative'}}>
  <DocumentCamera
    imageType="png"
    cameraFacing="environment"
    onPhotoTaken={handlePhotoTaken}
    onError={onError}
    samWasmUrl="/sam.wasm"
  />
  <DocumentUi
    showDetectionLayer={false}
    showCameraButtons
    placeholder={DocumentPlaceholderIcon.ID_DASH}
    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 DocumentPlaceholderIcon.

<DocumentUi placeholder="id-dash" />

Code Samples

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