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.