@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
• Explicit Teardown: destroy() method for deterministic resource cleanup
• UI State Inspection: uiStateKey (stabilized, visible state) and mappedUiStateKey (latest raw candidate before stabilization) getters

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 {
  createBlinkIdUxManager,
  HapticFeedbackManager,
} from "@microblink/blinkid-ux-manager";

// Create UX Manager (haptic feedback enabled by default)
const uxManager = await createBlinkIdUxManager(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:

| Browser | Support | | ------- | ------- | | Chrome for Android | ✅ Supported | | Firefox for Android | ✅ Supported | | Safari (iOS) | ❌ Not supported | | Desktop browsers | ❌ Not supported |

The API is designed primarily for Android devices using Chrome, where it works reliably. On unsupported platforms isHapticFeedbackSupported() returns false and vibration calls are silently ignored.

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.

Creating the UX Manager

Use the async createBlinkIdUxManager factory — direct constructor instantiation is not supported:

import { createBlinkIdUxManager } from "@microblink/blinkid-ux-manager";

const uxManager = await createBlinkIdUxManager(cameraManager, scanningSession);

// When done, release resources explicitly
uxManager.destroy();

Inspecting UI State

Two getters provide visibility into the current UI state:

• uxManager.uiStateKey — the stabilized, visible state key (what the UI shows)
• uxManager.mappedUiStateKey — the latest raw candidate key from the detector before stabilization (useful for debugging)

Note: Starting in v7.7.0, the manager automatically advances through intermediate transition states after PAGE_CAPTURED (e.g. PAGE_CAPTURED → FLIP_CARD → INTRO_BACK_PAGE for two-sided IDs). Integrations that depend on exact UI-state key sequences should account for these chained transitions.

Configuring Help Tooltip Delays

Tooltip delays can be configured via FeedbackUiOptions when creating the feedback UI:

createBlinkIdFeedbackUi(uxManager, cameraUi, {
  showHelpTooltipTimeout: 15000, // ms before tooltip appears
});

Deprecated: The setHelpTooltipShowDelay and setHelpTooltipHideDelay methods on BlinkIdUxManager are deprecated. Prefer configuring delays through FeedbackUiOptions instead.

See the example apps in the apps/examples directory in the GitHub repository for full 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.