JavaScript SDK

The JavaScript SDK is the default browser integration. It collects optional browser signals, hashes available values locally, and calls the hosted identify endpoint.

Install

bun add fingerprint.dev

Identify

import { identify } from "fingerprint.dev";

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

console.log(result.visitor_id);
console.log(result.confidence);

endpoint defaults to the hosted API origin, https://api.fingerprint.dev. You can also pass either a full identify URL or an API origin. If it does not end with /v1/identify, the SDK appends /v1/identify.

Options

type IdentifyOptions = {
  apiKey: string;
  endpoint?: string;
  timeout?: number;
  debug?: boolean;
};

• apiKey: required. Pass a dashboard key such as fp_live_....
• endpoint: optional. Defaults to https://api.fingerprint.dev.
• timeout: request timeout in milliseconds. Defaults to 10000.
• debug: logs request progress and signal availability. It does not log raw or hashed signal values.

Result

type IdentifyResult = {
  visitor_id: string | null;
  confidence: number | null;
  kind: "new" | "match";
  request_id: string;
  signals: {
    ja4?: string | null;
    ja4t?: string | null;
    ja4x?: string | null;
    ja4h?: string | null;
    js?: string | null;
  };
  browser_signals: {
    canvas: string | null;
    webgl: string | null;
    audio: string | null;
    screen: string | null;
    fonts: string | null;
    navigator: string | null;
  };
};

browser_signals contains the hashed browser evidence sent to the API. It is useful for local diagnostics, but you should avoid logging it in production.

Signal collection

You can collect and hash signals yourself if you need to inspect availability before calling the API:

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

let raw = await collectSignals();
let hashed = await hashSignals(raw);

if (hashed.webgl === null) {
  console.log("WebGL was unavailable or blocked");
}

Keep raw signal values inside the browser session. Do not store them in local storage, send them to your logs, or attach them to analytics events.

Errors

SDK failures throw IdentifyError:

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

try {
  let result = await identify({
    apiKey: "fp_live_...",
  });
  console.log(result.request_id);
} catch (err) {
  if (err instanceof IdentifyError) {
    console.log(err.code);
    console.log(err.statusCode);
  }
}

Common codes include INVALID_CONFIG, API_ERROR, INVALID_RESPONSE, TIMEOUT, NETWORK_ERROR, and UNKNOWN_ERROR.