fingerprint.dev

Browser client for fingerprint.dev. Collects browser-side signals, hashes them locally, and returns a stable visitor_id from the hosted /v1/identify endpoint.

Install

npm install fingerprint.dev

Quickstart

import { identify } from "fingerprint.dev";

let result = await identify({ apiKey: "fp_live_..." });

result.visitor_id;      // string | null  — stable per visitor
result.confidence;      // number | null  — 0.0 to 1.0
result.kind;            // "new" | "match"
result.request_id;      // string         — "req_..."
result.signals;         // server-side JA4 fingerprints
result.browser_signals; // hashed browser signals sent up

identify() throws Identify.Error on failure. The code field is one of INVALID_CONFIG, API_ERROR, TIMEOUT, NETWORK_ERROR, INVALID_RESPONSE, UNKNOWN_ERROR.

import { identify, Identify } from "fingerprint.dev";

try {
  var result = await identify({ apiKey: "fp_live_..." });
} catch (err) {
  if (err instanceof Identify.Error && err.code === "TIMEOUT") {
    // retry, fall back, etc.
  }
  throw err;
}

Options

| Option | Type | Default | Notes | | ---------- | --------- | ----------------------------- | ------------------------------------------------------ | | apiKey | string | — | Required. fp_live_* or fp_test_*. | | endpoint | string | https://api.fingerprint.dev | /v1/identify is appended automatically if missing. | | timeout | number | 10000 | Milliseconds. Aborts the request; throws TIMEOUT. | | debug | boolean | false | Logs request progress and signal availability. |

Signal semantics

The client collects six browser signals: canvas, webgl, audio, screen, fonts, navigator. Each is string | null — null means the browser API was blocked, unavailable, or failed. Null is preserved through hashing so unavailable APIs read as missing evidence rather than a stable pseudo-signal.

import { collectSignals, hashSignals } from "fingerprint.dev";

let raw = await collectSignals();    // Identify.RawSignals — debug/inspect only
let hashed = await hashSignals(raw); // Identify.HashedSignals — what gets sent

if (hashed.webgl === null) {
  // WebGL was unavailable or blocked.
}

Raw signal values never leave the browser. Only SHA-256 hashes (truncated to 12 hex chars) are sent. debug: true logs request progress and per-signal availability — it never logs raw or hashed signal values.

If crypto.subtle is unavailable (insecure context, ancient browser), identify() skips signal collection entirely and still calls the API so the server can produce a visitor id from connection-level fingerprints.

Exports

• identify(options) — collect, hash, send, return result
• collectSignals() — raw signals only (no network)
• hashSignals(raw) — hash without sending
• Identify — type namespace + the Error class
  • Identify.Error — thrown on failure; has code and optional statusCode
  • Types: Identify.Options, Identify.Result, Identify.Response, Identify.RawSignals, Identify.HashedSignals, Identify.SignalValue, Identify.Fingerprints