Skip to content

Browser Fingerprinting SDK: Identity vs Evidence

4 min read Notes

Browser Fingerprinting SDK: Identity vs Evidence

A browser fingerprinting sdk fails in a specific way: the identifier moves, and a returning customer becomes a stranger. The design decision that prevents it is separating identity from evidence, and @globus.studio/fingerprintjs builds the whole API around that line.

Code: Fingerprint-JS, MIT licensed.

No runtime dependencies, no network calls by default, ESM, CommonJS and a script-tag bundle, TypeScript types for every entry point.

The identifier is a hash of the stable set

import { loadClient } from '@globus.studio/fingerprintjs';

const client = await loadClient({
  namespace: 'my-product',
  useCase: 'fraud-defense',
  storage: 'local',
});
const result = await client.get({ consent: { granted: true, purpose: 'fraud-prevention' } });

visitorId comes from components marked hashable: true. Bot evidence, private-mode likelihood, network type, timings and storage capabilities are collected, scored and returned in components with hashable: false, and never enter the hash unless includeNonHashable is set for a diagnostic build.

result.meta.identityComponents and result.meta.reportOnlyComponents list what went where, so an incident review does not have to guess.

The backend has the last word

import { verifyFingerprintResult, createReplayToken, createMemoryReplayStore } from '@globus.studio/fingerprintjs/server';

The server package recomputes the hash, checks a replay token, and can attach a network risk verdict from its own side. verification.ok plus network.verdict is enough to raise friction, deny a request or send the event to BotBlocker Security.

Replay protection is the part most client libraries skip. A fingerprint result posted from a browser can be replayed by anyone who captured it, and a signed token with a store on the server is the cheapest fix.

Profiles and presets

Three profiles: strict for passive low-sensitivity signals, balanced for analytics defaults, extended for security work with active collectors. Six use-case presets: privacy-first, analytics-lite, login-risk, checkout-risk, bot-defense, fraud-defense.

Policy and identity controls are separate. policy sets consent gates, sensitivity limits and deny lists; identity decides which collectors may enter the hash. Mixing the two is how a privacy setting accidentally breaks the identifier.

What the build guarantees

A browser bundle under 65 KB, coverage at 100% for line, branch and function, Playwright tests in Chromium, Firefox and WebKit, and a size gate that fails the build above the budget.

The size gate matters for this library more than for most: it runs on every page view, and a bundle that grows to 200 KB becomes a performance bug the product team has to explain.

Reports for three audiences

A compact report for product code, a dense ID analysis report for backend scoring, and a full report with raw values for debugging. The inspector example takes any of them and explains identity components, report-only components and the bot, tamper and private-mode evidence.

Report shapes are a product decision. A backend that has to parse a raw SDK dump for a risk score ends up reimplementing the library’s logic in another language.

What the SDK does not decide

Whether a patched API is a scraper or a privacy extension, whether a private-mode user is a fraudster or a journalist, and whether the fingerprint may be stored at all.

Those are policy questions with legal consequences, and the readme keeps them out of the library on purpose.

The SDK also does not store anything on its own beyond the configured adapter. Whether a localStorage entry is acceptable on a page under a consent banner is a product decision, and the storage adapters are swappable for a reason: the answer changes per country.

Related: python readability package for another package with strict typing and honest limits, and islands architecture for a design where the payload stays small by default.

Custom work

Need an API that does not exist yet?

Describe the task and the response format. We will estimate the endpoint, the integration and the maintenance.

Start a conversation