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 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 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 change 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 values 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.