capacitor-zkteco-fingerprint

A Capacitor plugin for integrating the ZKTeco Live10R USB Fingerprint Scanner into Android applications.

The plugin wraps the official ZKTeco Android SDK and provides a simple JavaScript API for connecting to the scanner, capturing fingerprints, enrolling users, and verifying fingerprint templates.

Platform Support

• ✅ Android
• ❌ iOS (Not Supported)
• ❌ Web (Not Supported)

Features

• Initialize the ZKTeco SDK
• Connect to the fingerprint scanner
• Disconnect the scanner
• Capture fingerprint templates
• Enroll fingerprints
• Verify fingerprint templates
• Returns Base64 encoded fingerprint templates
• Built specifically for Capacitor v4

Requirements

• Capacitor 4.x
• Android device with USB Host (OTG) support
• ZKTeco Live10R USB Fingerprint Scanner

Installation

Using npm

npm install capacitor-zkteco-fingerprint

Using Yarn

yarn add capacitor-zkteco-fingerprint

Sync your Capacitor project

npx cap sync

Import

import { Fingerprint } from "capacitor-zkteco-fingerprint";

Quick Start

// Initialize SDK
await Fingerprint.initialize();

// Connect scanner
const device = await Fingerprint.connect();

if (!device.connected) {
  console.log("Scanner not found.");
  return;
}

// Capture fingerprint
const capture = await Fingerprint.capture();

console.log(capture.template);

// Verify fingerprint
const result = await Fingerprint.verify({
  template: capture.template,
});

console.log(result.matched);
console.log(result.score);

// Disconnect
await Fingerprint.disconnect();

Typical Workflow

Initialize SDK
      │
      ▼
Connect Scanner
      │
      ▼
Capture Fingerprint
      │
      ▼
Store Template
      │
      ▼
Verify Template
      │
      ▼
Disconnect Scanner

Best Practices

• Call initialize() once when your application starts.
• Connect only when fingerprint operations are required.
• Disconnect the scanner after operations are complete.
• Store only the returned fingerprint template in your backend or database.
• Avoid running multiple fingerprint operations simultaneously.

Error Handling

try {
  await Fingerprint.connect();

  const result = await Fingerprint.capture();

  console.log(result.template);
} catch (err) {
  console.error(err);
}

Troubleshooting

Scanner not detected

• Verify the scanner is connected.
• Ensure the Android device supports USB OTG.
• Grant USB permission when prompted.
• Disconnect and reconnect the scanner.

Verification always fails

• Ensure the stored fingerprint template has not been modified.
• Capture a new enrollment template if necessary.
• Verify using templates generated by the same SDK.

API

• initialize()
• connect()
• disconnect()
• capture()
• enroll(...)
• verify(...)

initialize()

initialize() => Promise<void>

connect()

connect() => Promise<{ connected: boolean; serial?: string; firmware?: string; }>

Returns: Promise<{ connected: boolean; serial?: string; firmware?: string; }>

disconnect()

disconnect() => Promise<void>

capture()

capture() => Promise<{ template: string; }>

Returns: Promise<{ template: string; }>

enroll(...)

enroll(options: { userId: string; }) => Promise<{ template: string; }>

| Param | Type | | ------------- | -------------------------------- | | options | { userId: string; } |

Returns: Promise<{ template: string; }>

verify(...)

verify(options: { template: string; }) => Promise<{ matched: boolean; score: number; }>

| Param | Type | | ------------- | ---------------------------------- | | options | { template: string; } |

Returns: Promise<{ matched: boolean; score: number; }>

Compatibility

| Plugin Version | Capacitor | |----------------|-----------| | 1.0.0 | 4.x |

License

MIT