@microblink/blinkid-ux-manager

This package provides user experience management and feedback UI for the BlinkID browser SDK. It parses results from @microblink/blinkid-core and guides the user through the scanning process, controlling @microblink/camera-manager as needed.

Features

• Smart UI State Management: Provides both headless and UI components for user feedback during scanning
• Camera Integration: Integrates with BlinkID Core and Camera Manager
• Haptic Feedback: Built-in haptic feedback support for enhanced user experience on mobile devices
• Document Filtering: Advanced document class filtering capabilities
• Timeout Management: Configurable scanning timeouts with automatic state management
• Localization Support: Multi-language support with customizable strings

Overview

• Provides both headless and UI components for user feedback during scanning.
• Integrates with BlinkID Core and Camera Manager.
• Includes haptic feedback system for mobile devices.
• Used by @microblink/blinkid and can be used directly for custom UI integrations.

Installation

Install from npm using your preferred package manager:

npm install @microblink/blinkid-ux-manager
# or
yarn add @microblink/blinkid-ux-manager
# or
pnpm add @microblink/blinkid-ux-manager

Haptic Feedback

The UX Manager includes a comprehensive haptic feedback system that provides tactile responses during the document scanning process. This feature is primarily designed for Android devices using Chrome browser, where it works reliably to enhance the scanning experience.

Haptic Feedback Types

| Event | Duration | Type | Description | | ------------------ | -------- | ----- | --------------------------------------------- | | First Side Success | 100ms | Short | When the first side of an ID card is captured | | Final Success | 300ms | Long | When document scanning is completed | | Error States | 100ms | Short | Quality issues (blur, glare, positioning) | | Error Dialogs | 300ms | Long | Timeout or critical errors | | Flashlight Toggle | 100ms | Short | When camera flashlight is activated | | Warning States | 100ms | Short | During sensing phases (with 1s cooldown) |

Haptic Feedback Usage

import {
  BlinkIdUxManager,
  HapticFeedbackManager,
} from "@microblink/blinkid-ux-manager";

// Create UX Manager (haptic feedback enabled by default)
const uxManager = new BlinkIdUxManager(cameraManager, scanningSession);

// Check if haptic feedback is supported
if (uxManager.isHapticFeedbackSupported()) {
  console.log("Device supports haptic feedback");
}

// Enable/disable haptic feedback
uxManager.setHapticFeedbackEnabled(true); // Enable
uxManager.setHapticFeedbackEnabled(false); // Disable

// Access haptic manager directly for manual control
const hapticManager = uxManager.getHapticFeedbackManager();
hapticManager.triggerShort(); // 100ms vibration for short feedback
hapticManager.triggerLong(); // 300ms vibration for long feedback
hapticManager.stop(); // Stop all vibration

Browser Compatibility

⚠️ Important: Haptic feedback uses the Web Vibration API, which has limited browser support:

Usage

You can use @microblink/blinkid-ux-manager directly in your project for advanced or custom integrations. For most use cases, use @microblink/blinkid for a simpler setup.

See the example apps in the apps/examples directory in the GitHub repository for usage details.

Development

To build the package locally:

1. Install dependencies in the monorepo root:

   pnpm install

2. Build the package:

   pnpm build

3. Run tests:

   pnpm test

The output files will be available in the dist/ and types/ directories.

Internationalization

You can customize UI strings when creating the feedback UI:

createBlinkIdFeedbackUi(uxManager, cameraUi, {
   localizationStrings: {
      scan_the_barcode: "Please scan the barcode"
   }
});

Provided Translations

• ak.ts
• am.ts
• ar.ts
• bn.ts
• cs.ts
• da.ts
• de.ts
• el.ts
• en.ts
• en_GB.ts
• es.ts
• es_MX.ts
• fa-latn.ts
• fi.ts
• fil.ts
• fr.ts
• fr_CA.ts
• ha.ts
• he.ts
• hi.ts
• hr.ts
• hu.ts
• id.ts
• is.ts
• it.ts
• ja.ts
• ka_GE.ts
• kk.ts
• km_KH.ts
• ko.ts
• lv.ts
• ms.ts
• ne.ts
• nl.ts
• no.ts
• pl.ts
• ps_AF.ts
• pt.ts
• pt_BR.ts
• ro.ts
• ru.ts
• si.ts
• sk.ts
• sl.ts
• sr.ts
• sv.ts
• sw.ts
• th.ts
• tr.ts
• uk.ts
• ur.ts
• uz.ts
• vi.ts
• yo.ts
• zh_CN.ts
• zh_TW.ts

You can import any of these files directly or use them as a starting point for your own localization.