DOT Web Auto Capture 8.0.0

Introduction

Version 8.0.0 introduces significant changes to improve API consistency and developer experience across all DOT Web Auto Capture components. The main areas of change are:

Configuration API restructuring - Unified naming convention for component properties
Threshold API restructuring - Simplified and more intuitive threshold property names
UI configuration nesting - Related UI properties grouped into logical objects
Transaction reporting - Now enabled by default (requires token when transaction reporting is included in license)
Analytics provider change - Switched from Countly to Innovatrics Metrics Middleware
Smile Liveness callback and event changes - OnComplete data structure and events restructured
Multi-Range Liveness callback changes - OnComplete data structure updated
Firefox deprecation - Firefox browser support is deprecated
MagnifEye Liveness deprecation - Component is deprecated, use Multi-Range Liveness instead

Migration Steps

1. Update Package Versions

Update all DOT Web Auto Capture packages to version 8.0.0:

npm install @innovatrics/dot-face-auto-capture@8.0.0
npm install @innovatrics/dot-document-auto-capture@8.0.0
npm install @innovatrics/dot-smile-liveness@8.0.0
npm install @innovatrics/dot-palm-auto-capture@8.0.0
npm install @innovatrics/dot-multi-range-liveness@8.0.0
npm install @innovatrics/dot-auto-capture-ui@8.0.0

2. Configuration Property Renaming

The main configuration property has been renamed for consistency across all components.

Non-UI Components

Component	Before	After
Face Auto Capture	`cameraOptions`	`configuration`
Document Auto Capture	`cameraOptions`	`configuration`
Palm Auto Capture	`cameraOptions`	`configuration`
Smile Liveness	`props`	`configuration`
Multi-Range Liveness	`props`	`configuration`

Before

const faceElement = document.getElementById(
  "x-dot-face-auto-capture"
) as HTMLFaceCaptureElement;
faceElement.cameraOptions = {
  onPhotoTaken: handlePhotoTaken,
  onError: handleError,
};

After

const faceElement = document.getElementById(
  "x-dot-face-auto-capture"
) as HTMLFaceCaptureElement;
faceElement.configuration = {
  onComplete: handleComplete,
  onError: handleError,
};

3. Type Renaming

Update your type imports to use the new names:

Component	Before	After
Face Auto Capture	`FaceCameraProps`	`FaceConfiguration`
Face Auto Capture	`HTMLFaceCaptureElement.cameraOptions`	`HTMLFaceCaptureElement.configuration`
Document Auto Capture	`DocumentCameraProps`	`DocumentConfiguration`
Document Auto Capture	`HTMLDocumentCaptureElement.cameraOptions`	`HTMLDocumentCaptureElement.configuration`
Palm Auto Capture	`PalmCameraProps`	`PalmConfiguration`
Palm Auto Capture	`HTMLPalmCaptureElement.cameraOptions`	`HTMLPalmCaptureElement.configuration`
Smile Liveness	`SmileLivenessProps`	`Configuration`
Smile Liveness	`HTMLSmileLivenessElement.props`	`HTMLSmileLivenessElement.configuration`
Multi-Range Liveness	`Configuration`	`Configuration` (no change)
Multi-Range Liveness	`HTMLMultiRangeLivenessElement.props`	`HTMLMultiRangeLivenessElement.configuration`

4. Callback Renaming

The main completion callback has been renamed for certain components:

Component	Before	After
Face Auto Capture	`onPhotoTaken`	`onComplete`
Document Auto Capture	`onPhotoTaken`	`onComplete`
Palm Auto Capture	`onPhotoTaken`	`onComplete`

The callback parameter data has been renamed to imageData.

Before

faceElement.cameraOptions = {
  onPhotoTaken: (imageData, data) => {
    console.log(imageData.image);
    console.log(data);
  },
};

After

faceElement.configuration = {
  onComplete: (imageData) => {
    console.log(imageData.image);
    console.log(imageData);
  },
};

5. Threshold Property Renaming

The thresholds property has been renamed to qualityAttributeThresholds across all components.

Before

faceElement.cameraOptions = {
  thresholds: {
    faceConfidence: 0.12,
    sharpnessThreshold: 0.25,
  },
};

After

faceElement.configuration = {
  qualityAttributeThresholds: {
    confidence: 0.12,
    sharpness: 0.25,
  },
};

6. Threshold API Restructuring (Component-Specific)

Each component has specific threshold property name changes:

Face Auto Capture

Before	After
`faceConfidence`	`confidence`
`sharpnessThreshold`	`sharpness`
`brightnessHighThreshold`	`brightness.max`
`brightnessLowThreshold`	`brightness.min`
`minFaceSizeRatio`	`size.min`
`maxFaceSizeRatio`	`size.max`
`devicePitchAngleThreshold`	`devicePitchAngle`
`outOfBoundsThreshold`	`edgeDistanceToImageShorterSideRatio`

Document Auto Capture

Before	After
`sharpnessThreshold`	`sharpness`
`brightnessHighThreshold`	`brightness.max`
`brightnessLowThreshold`	`brightness.min`
`hotspotsScoreThreshold`	`hotspotsScore`
`sizeSmallThreshold`	`size`
`outOfBoundsThreshold`	`edgeDistanceToImageShorterSideRatio`

Palm Auto Capture

Before	After
`confidenceThreshold`	`confidence`
`sharpnessThreshold`	`sharpness`
`brightnessHighThreshold`	`brightness.max`
`brightnessLowThreshold`	`brightness.min`
`sizeIntervalThreshold.min`	`size.min`
`sizeIntervalThreshold.max`	`size.max`
`outOfBoundsThreshold`	`edgeDistanceToImageShorterSideRatio`
`minTemplateExtractionQualityThreshold`	`templateExtractionQuality`

Smile Liveness

Before	After
`minFaceSizeRatio`	`size.min`
`maxFaceSizeRatio`	`size.max`

7. UI Component Configuration Restructuring

UI component properties have been reorganized into nested objects for better organization.

Property Changes

Before	After
`props`	`configuration`
`showCameraButtons`	`control.showCameraButtons`
`showDetectionLayer`	`control.showDetectionLayer`
`backdropColor`	`styling.backdropColor`
`theme`	`styling.theme`

UI Type Renaming

Component	Before	After
Face UI	`FaceUiProps`	`FaceUiConfiguration`
Face UI	`HTMLFaceUiElement.props`	`HTMLFaceUiElement.configuration`
Document UI	`DocumentUiProps`	`DocumentUiConfiguration`
Document UI	`HTMLDocumentUiElement.props`	`HTMLDocumentUiElement.configuration`
Smile UI	`SmileLivenessUiProps`	`SmileLivenessUiConfiguration`
Smile UI	`HTMLSmileLivenessUiElement.props`	`HTMLSmileLivenessUiElement.configuration`
Palm UI	`PalmUiProps`	`PalmUiConfiguration`
Palm UI	`HTMLPalmUiElement.props`	`HTMLPalmUiElement.configuration`
Multi-Range UI	`MultiRangeUiProps`	`MultiRangeUiConfiguration`
Multi-Range UI	`HTMLMultiRangeLivenessUiElement.props`	`HTMLMultiRangeLivenessUiElement.configuration`

Before

const uiElement = document.getElementById(
  "x-dot-face-auto-capture-ui"
) as HTMLFaceUiElement;
uiElement.props = {
  showCameraButtons: true,
  showDetectionLayer: true,
  backdropColor: "rgba(0, 0, 0, 0.5)",
  theme: {
    colors: {
      placeholderColor: "green",
    },
  },
  instructions: {
    face_not_present: "Show your face",
  },
};

After

const uiElement = document.getElementById(
  "x-dot-face-auto-capture-ui"
) as HTMLFaceUiElement;
uiElement.configuration = {
  control: {
    showCameraButtons: true,
    showDetectionLayer: true,
  },
  styling: {
    backdropColor: "rgba(0, 0, 0, 0.5)",
    theme: {
      colors: {
        placeholderColor: "green",
      },
    },
  },
  instructions: {
    face_not_present: "Show your face",
  },
};

8. Transaction Counting Token (Required)

Transaction reporting is now enabled by default. You must provide a transactionCountingToken in the initialization phase when transaction reporting is included in license.

Before (Optional)

faceElement.cameraOptions = {
  onPhotoTaken: handlePhotoTaken,
  onError: handleError,
  // transactionCountingToken was optional
};

After (Required)

faceElement.configuration = {
  onComplete: handleComplete,
  onError: handleError,
  transactionCountingToken: "your-transaction-counting-token",
};

Contact your Innovatrics representative to obtain a transaction counting token for your license.

9. Removed Face Placeholders

The following face placeholder icons have been removed:

ELLIPSE_SOLID
MAN_SOLID
WOMAN_SOLID

If you were using any of these placeholders, switch to one of the available alternatives:

CIRCLE_SOLID
SQUARE_ROUNDED_DASH
SQUARE_ROUNDED_SOLID
SQUARE_DASH
SQUARE_SOLID

10. Smile Liveness: OnComplete Callback Data Structure Change

The onComplete callback data structure has changed from an array to a labeled object.

Before

function handleOnComplete(data: Array<OnCompleteData>, content: Uint8Array) {
  const [neutralFace, smileFace] = data;
  console.log(neutralFace.data, neutralFace.image);
  console.log(smileFace.data, smileFace.image);
}

After

import type { OnCompleteCallbackImages } from "@innovatrics/dot-smile-liveness";

function handleOnComplete(
  resultData: OnCompleteCallbackImages,
  content: Uint8Array
) {
  console.log(
    resultData.neutralPhaseImageWithMetadata.data,
    resultData.neutralPhaseImageWithMetadata.image
  );
  console.log(
    resultData.smilePhaseImageWithMetadata.data,
    resultData.smilePhaseImageWithMetadata.image
  );
}

11. Smile Liveness: Event Changes

The smile-auto-capture:status-changed event has been split into two separate events for better clarity.

Before	After
`smile-auto-capture:status-changed`	`smile-auto-capture:phase-changed` (for phase changes)
	`smile-auto-capture:state-changed` (for state changes)

Before

import { SmileCustomEvent } from "@innovatrics/dot-smile-liveness/events";

document.addEventListener(SmileCustomEvent.STATUS_CHANGED, (event) => {
  const { state, phase } = event.detail;
});

After

import { SmileCustomEvent } from "@innovatrics/dot-smile-liveness/events";

document.addEventListener(SmileCustomEvent.PHASE_CHANGED, (event) => {
  console.log(event.detail.phase);
});

document.addEventListener(SmileCustomEvent.STATE_CHANGED, (event) => {
  console.log(event.detail.appState);
});

12. Multi-Range Liveness: OnComplete Callback Data Structure Change

The onComplete callback result data is now wrapped in an object with imageWithMetadata property.

After

function handleOnComplete(
  resultData: OnCompleteCallbackImage,
  content: Uint8Array
) {
  console.log(
    resultData.imageWithMetadata.data,
    resultData.imageWithMetadata.image
  );
}

13. Firefox Browser Deprecation

Firefox browser support is deprecated due to incompatibility with required web platform features and will be discontinued in the next major release. A warning message will be displayed on localhost when using Firefox.

We recommend transitioning users to Chrome, Safari, or Edge browsers for the best experience.

14. MagnifEye Liveness Deprecation

MagnifEye Liveness component is deprecated and will be discontinued in the next major release. A warning message will be displayed on localhost when using this component.

Migration path: Please migrate to Multi-Range Liveness component, which provides improved liveness detection capabilities and will continue to be supported and enhanced.

If you are currently using MagnifEye Liveness:

// Before (deprecated)
import '@innovatrics/dot-magnifeye-liveness';

<x-dot-magnifeye-liveness configuration={...} />

Migrate to Multi-Range Liveness:

// After (recommended)
import '@innovatrics/dot-multi-range-liveness';

<x-dot-multi-range-liveness configuration={...} />

Contact your Innovatrics representative for assistance with the migration.

Complete Migration Example

Face Auto Capture - Before (Version 7)

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

const faceElement = document.getElementById(
  "x-dot-face-auto-capture"
) as HTMLFaceCaptureElement;
faceElement.cameraOptions = {
  onPhotoTaken: (imageData, data) => {
    console.log(imageData.image);
  },
  onError: handleError,
  thresholds: {
    faceConfidence: 0.12,
    sharpnessThreshold: 0.25,
    brightnessLowThreshold: 0.25,
    brightnessHighThreshold: 0.9,
    minFaceSizeRatio: 0.16,
    maxFaceSizeRatio: 0.2,
  },
};

const uiElement = document.getElementById(
  "x-dot-face-auto-capture-ui"
) as HTMLFaceUiElement;
uiElement.props = {
  showCameraButtons: true,
  showDetectionLayer: true,
  backdropColor: "rgba(0, 0, 0, 0.5)",
  theme: {
    colors: {
      placeholderColor: "green",
    },
  },
};

Face Auto Capture - After (Version 8)

import type {
  FaceConfiguration,
  HTMLFaceCaptureElement,
} from "@innovatrics/dot-face-auto-capture";
import type {
  FaceUiConfiguration,
  HTMLFaceUiElement,
} from "@innovatrics/dot-auto-capture-ui/face";

const faceElement = document.getElementById(
  "x-dot-face-auto-capture"
) as HTMLFaceCaptureElement;
faceElement.configuration = {
  onComplete: (imageData) => {
    console.log(imageData.image);
  },
  onError: handleError,
  transactionCountingToken: "your-transaction-counting-token",
  qualityAttributeThresholds: {
    confidence: 0.12,
    sharpness: 0.25,
    brightness: {
      min: 0.25,
      max: 0.9,
    },
    size: {
      min: 0.16,
      max: 0.2,
    },
  },
};

const uiElement = document.getElementById(
  "x-dot-face-auto-capture-ui"
) as HTMLFaceUiElement;
uiElement.configuration = {
  control: {
    showCameraButtons: true,
    showDetectionLayer: true,
  },
  styling: {
    backdropColor: "rgba(0, 0, 0, 0.5)",
    theme: {
      colors: {
        placeholderColor: "green",
      },
    },
  },
};

Summary of Breaking Changes

Change	Action Required
`cameraOptions` / `props` → `configuration`	Update property name
Type renames (e.g., `FaceCameraProps` → `FaceConfiguration`)	Update type imports
`onPhotoTaken` → `onComplete`	Rename callback
`thresholds` → `qualityAttributeThresholds`	Rename property
Threshold property name changes	Update threshold property names
UI props restructured (`showCameraButtons` → `control.showCameraButtons`, etc.)	Nest UI properties
Transaction counting token required	Provide `transactionCountingToken`
Removed face placeholders (`ELLIPSE_SOLID`, `MAN_SOLID`, `WOMAN_SOLID`)	Use alternative placeholders
Smile: `OnCompleteData[]` → `OnCompleteCallbackImages`	Update callback parameter handling
Smile: `status-changed` → `phase-changed` + `state-changed`	Update event listeners
Multi-Range: OnComplete data wrapped in `imageWithMetadata`	Update callback parameter handling
Firefox deprecated	Inform users, plan migration
MagnifEye Liveness deprecated	Migrate to Multi-Range Liveness

Code Samples

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

Introduction​

Migration Steps​

1. Update Package Versions​

2. Configuration Property Renaming​

Non-UI Components​

Before​

After​

3. Type Renaming​

4. Callback Renaming​

Before​

After​

5. Threshold Property Renaming​

Before​

After​

6. Threshold API Restructuring (Component-Specific)​

Face Auto Capture​

Document Auto Capture​

Palm Auto Capture​

Smile Liveness​

7. UI Component Configuration Restructuring​

Property Changes​

UI Type Renaming​

Before​

After​

8. Transaction Counting Token (Required)​

Before (Optional)​

After (Required)​

9. Removed Face Placeholders​

10. Smile Liveness: OnComplete Callback Data Structure Change​

Before​

After​

11. Smile Liveness: Event Changes​

Before​

After​

12. Multi-Range Liveness: OnComplete Callback Data Structure Change​

After​

13. Firefox Browser Deprecation​

14. MagnifEye Liveness Deprecation​

Complete Migration Example​

Face Auto Capture - Before (Version 7)​

Face Auto Capture - After (Version 8)​

Summary of Breaking Changes​

Code Samples​

Introduction

Migration Steps

1. Update Package Versions

2. Configuration Property Renaming

Non-UI Components

Before

After

3. Type Renaming

4. Callback Renaming

Before

After

5. Threshold Property Renaming

Before

After

6. Threshold API Restructuring (Component-Specific)

Face Auto Capture

Document Auto Capture

Palm Auto Capture

Smile Liveness

7. UI Component Configuration Restructuring

Property Changes

UI Type Renaming

Before

After

8. Transaction Counting Token (Required)

Before (Optional)

After (Required)

9. Removed Face Placeholders

10. Smile Liveness: OnComplete Callback Data Structure Change

Before

After

11. Smile Liveness: Event Changes

Before

After

12. Multi-Range Liveness: OnComplete Callback Data Structure Change

After

13. Firefox Browser Deprecation

14. MagnifEye Liveness Deprecation

Complete Migration Example

Face Auto Capture - Before (Version 7)

Face Auto Capture - After (Version 8)

Summary of Breaking Changes

Code Samples