What it does
getDeviceId forces the binding filter to hardware-only regardless of anything in the options argument. Engine-bound collectors are skipped entirely; only the hardware-bound signal set runs. The specific signals in that set are part of the internal recipe and not part of the public contract.
The result is faster (about 200 to 300 ms vs 1 to 1.5 s for getFingerprint) and produces a hash that does not change when the user switches browsers, opens an incognito window, or clears their browser cache. On any uncaught error the function returns an empty DeviceIdResult rather than throwing.
When to use it
Use getDeviceId whenever you need to identify the physical device rather than a specific browser session. Common cases: MFA step-up (has this user authenticated from this device before?), cross-browser device linking (same hardware seen in Chrome and Safari?), and software license enforcement (is this device already registered?).
When you also need browser-level signals (spoofing detection, bot detection, or distinguishing two users sharing the same machine), use getFingerprint instead, which runs the full pipeline and returns both hashes.
Return shape
DeviceIdResult is a focused subset of FingerprintResult. The id field is the hardware hash. The signals map contains only the hardware signals that were collected; raw values appear only when debug: true is set.
DeviceIdResult fields
| Field | Type | Description |
|---|---|---|
| id | string | 16-char hex hardware fingerprint. Same value as hardwareFingerprint in FingerprintResult. |
| confidence | number | 0.0 to 1.0 collection quality score derived from the cross-browser hardware hash. |
| stableSignals | string[] | Signal names that contributed to the hardware hash. |
| unstableSignals | string[] | Signal names that were collected but excluded from the hardware hash. |
| consistency | ConsistencyResult | Anti-detect browser detection: spoofLikelihood and flags. |
| incognito | IncognitoResult | Private-mode detection: incognitoLikelihood and flags. |
| automation | AutomationResult | Automation-framework detection: automationLikelihood and flags. |
| collectionTimeMs | number | Wall-clock time the hardware collection pass took. |
| version | string | Library version string. |
| signals | Record<string, SignalResult> | Per-signal result map. Hardware signals only. |
| errors | FingerprintError[] | undefined | Optional. Present only when at least one collector or pipeline failure occurred during the hardware collection pass. A clean run omits the field entirely. Each entry has a 'type' ('collector_threw' | 'collector_timeout' | 'fatal'), optional 'component' name, and a message capped at 200 characters. Errors are diagnostic only and never feed into the hash. |
Per-signal error messages
When a hardware collector throws or times out, an optional `errorMessage` string is attached to the corresponding `signals[name]` entry. The same diagnostic is lifted into the top-level `errors` array with `type: 'collector_threw'` or `type: 'collector_timeout'`. Because getDeviceId only runs hardware-bound collectors, the typical surface area for errors is small. Fonts and media_devices are the most likely to need diagnostics on restrictive platforms.
If the orchestrator itself throws, a single `type: 'fatal'` entry is emitted and the function returns an empty DeviceIdResult rather than throwing.
import { getDeviceId } from 'doorman-benny'; const { id, confidence, consistency, incognito } = await getDeviceId(); // Use id as a stable device identifier, consistent across browsers and incognito.
console.log(id); // "7c2e9a4b8f1d6e3a"
console.log(confidence); // 0.82 // Check for anti-detect tooling even on the hardware path.
if (consistency.spoofLikelihood === 'high') { flagForReview('Anti-detect browser on hardware collection');
} // Opt in to tier 2 for media_devices coverage.
const result2 = await getDeviceId({ tiers: [1, 2] });
console.log(result2.id);getDeviceId accepts the same FingerprintOptions as getFingerprint. The bindings filter is forced to hardware-only and cannot be overridden.
Last reviewed 2026-06-04
