SDK Documentation
// Low-Level Integration Kits
ZKTeco SDK Integration
For systems integrators building proprietary POS systems, custom kiosk interfaces, desktop enrollment applications, or specialized access control panels, the ZKTeco SDK suite provides direct, low-level execution alongside physical biometric sensors.
The SDK landscape spans domain-specific toolkits tailored for Windows, Linux, and Android, covering fingerprint, palm, and facial recognition hardware.
Pull SDK vs Push SDK (ADMS)
A fundamental architectural distinction within the ZKTeco ecosystem is how standalone biometric terminals communicate over network protocols.
Pull SDK
Traditional polling paradigm. The central middleware constantly dispatches requests across LAN to the terminal, which listens on TCP port 4370.
- Requires static IP allocation per terminal
- Complex firewall port-forwarding for WAN deployments
- Bandwidth saturation and latency issues
- Largely deprecated by ZKTeco
Push SDK (ADMS)
Event-driven HTTP protocol. The terminal acts as an active HTTP client, pushing data to a passive server — identical to standard outbound web traffic.
- Deploy anywhere with outbound internet access
- Negotiates firewalls autonomously
- Periodic heartbeats + event-triggered transmissions
- Tab-separated payloads for minimal bandwidth
Push Protocol — Device Polling & Data Transmission
// 1. Device checks for pending commands GET /iclock/getrequest?SN=XXXXXXXXXX → Response: "OK" (no pending commands) // 2. User clocks in → device pushes event POST /iclock/cdata?SN=XXXXXXXXXX&table=ATTLOG&Stamp=9999 // 3. Payload format (tab-separated): // PIN \t Timestamp \t VerifyType \t PunchState 2\t2022-07-12 16:00:20\t1\t15\t\t0\t0
Biometrics Module SDKs
The ZKFinger SDK is the cornerstone toolkit for integrating optical and capacitive fingerprint scanners (SLK20R, ZK9500, ZK8500R). Distributed in architecture-specific bundles for Windows (32/64-bit), Linux, and Android.
The ZKPalm SDK interfaces with PV10R and PV10M modules, leveraging a 3-in-1 palm recognition algorithm (palm shape, palm print, palm vein) for exceptional anti-spoofing capabilities.
Integration Lifecycle
Hardware Initialization (Init)
Allocate memory and establish logical connections to the USB bus. Failure to detect the hardware yields standard error codes (e.g., SDK Error -1).
Image Acquisition
When a finger is presented to the optical sensor, the SDK captures the raw bitmap image data into a pre-allocated byte array buffer.
Feature Extraction & Templating
Extract unique minutiae points from the raw image. Generate proprietary ZKTeco V10.0 templates or output interoperable ISO19794-2 / ANSI378 formats to prevent vendor lock-in.
Verification & Identification
Perform 1:1 matching (ZKMatch) against a claimed template, or rapid 1:N identification across hundreds of stored templates in local memory.
Resource Termination
Gracefully release device handles to prevent memory leaks and USB port locking upon application closure.
Facial Recognition SDKs
Visible Light Facial Recognition
Authenticate individuals walking within a 3-meter range at up to 30° off-center. Designed for heavy edge-computing environments — transforms passive surveillance camera arrays into active identity gateways. Returns simple boolean verification logic to trigger door relays or notifications.
AMTFaceLite SDK (Near-Infrared)
Processes Near-Infrared (NIR) video streams for high-security, anti-spoofing scenarios where ambient lighting is unpredictable. Requires 8-bit grayscale image data (256-gray scale) with explicit height and width parameters.
AMTFaceLite API Functions
| Function | Purpose |
|---|---|
| AMTNIRFace_Version | Returns the current algorithm library iteration. |
| AMTNIRFace_DetectAndGetPos | Handles spatial detection of a face within the camera's field of view. |
| AMTNIRFace_GetLiveness | Analyzes topological depth to ensure a live human — counters presentation attacks (photos, 3D masks). |
| AMTNIRFace_DBAdd | Manages localized RAM-based template enrollment. |
| AMTNIRFace_DBIdentify | Performs rapid 1:N algorithmic matching against enrolled users. |
ZKOnline SDK — Web Integration
Facilitates browser-level biometric enrollment without heavy desktop applications. Functions as a background service bridge between modern web browsers and localized USB hardware, allowing fingerprint template capture directly into web forms during HR onboarding.
Limitation: Currently restricted to 32-bit architectures — potential friction when scaling within modern 64-bit environments.
Best Practices & Troubleshooting
DLL Registration (Windows)
Ensure zkemkeeper.dll is correctly registered via regsvr32. The bit-architecture (32 vs 64-bit) of the compiled SDK must match the target OS.
Firmware Version Matching
Version mismatches between edge terminal firmware and deployed SDK libraries routinely cause unhandled exception errors. Always verify compatibility before deployment.
Network Configuration (Pull SDK)
Assign static IP addresses via Comm. → TCP/IP → Gateway on the device. Verify that firewalls permit TCP port 4370 traffic.
Memory Management
The Windows SDK relies on dynamic link libraries executing through a tightly managed memory lifecycle. Always release device handles on application closure to prevent USB locking.