DOT Web Auto Capture 8.0.0

This guide describes how to migrate DOT Web Auto Capture components from version 7 to version 8.

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:

1. Configuration API restructuring - Unified naming convention for component properties
2. Threshold API restructuring - Simplified and more intuitive threshold property names
3. UI configuration nesting - Related UI properties grouped into logical objects
4. Transaction reporting - Now enabled by default (requires token when transaction reporting is included in license)
5. Analytics provider change - Switched from Countly to Innovatrics Metrics Middleware
6. Smile Liveness callback and event changes - OnComplete data structure and events restructured
7. Multi-Range Liveness callback changes - OnComplete data structure updated
8. Firefox deprecation - Firefox browser support is deprecated
9. 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#

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:

4. Callback Renaming#

The main completion callback has been renamed for certain components:

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#

Document Auto Capture#

Palm Auto Capture#

Smile Liveness#

7. UI Component Configuration Restructuring#

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

Property Changes#

UI Type Renaming#

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#

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#

Code Samples#

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