@tracetail/js

@tracetail/js

Browser fingerprinting with 99.6% accuracy. TraceTail gives each browser a stable visitor ID without cookies or storage, so a visitor keeps the same ID after clearing cookies and in incognito windows. Use it to stop free-trial abuse, link duplicate accounts, flag sign-ins from new devices and spot automated browsers.

Install

npm install @tracetail/js

Quick start

import { TraceTail } from '@tracetail/js';

const tracetail = new TraceTail({ apiKey: 'YOUR_API_KEY', endpoint: 'https://tracetail.io/api' });
const { visitorId } = await tracetail.generateFingerprint();
// Send visitorId to your backend with the request you want to recognise.

Create a free API key at tracetail.io/auth. Without apiKey the SDK runs keyless: the visitor ID is computed in the browser, nothing is sent anywhere, and nothing appears in your dashboard. A script-tag version of the SDK is described in the docs.

Options

Creating a TraceTail touches no browser APIs, so it is safe at module level in server-rendered apps. Call generateFingerprint() in the browser.

generateFingerprint(options?)

The result:

Each TraceTail instance keeps its result in memory for the life of the page, and concurrent calls share one request. Nothing is written to cookies or storage.

Errors

API failures never reject: you still get visitorId, and error says what went wrong. Failures are not cached, so the next call tries again.

Other unexpected responses report HTTP_ERROR or INVALID_RESPONSE. generateFingerprint() rejects only when it runs without a DOM (server-side rendering) or when the browser throws while a signal is read.

API keys and domains

API keys are public: they ship in your page's code. Each key is locked to the domain you registered. A key for example.com works on example.com, www.example.com and every other subdomain, and a localhost key works on localhost on any port. The API checks the page's origin, so identify visitors in the browser, not from your server.

Verify on your server

The visitor ID comes from the browser, so your backend can't tell a real one from one a script made up. Before you trust it for a sign-up, login or payment, send the requestId from generateFingerprint() along and look it up with the Server API and a secret server key (tts_…, created in Settings → API keys and kept on your server):

curl https://tracetail.io/api/v1/identifications/$REQUEST_ID \
  -H "Authorization: Bearer $TRACETAIL_SERVER_KEY"

Check that the returned visitorId is the one your page sent, that createdAt is recent and that domain is your site. A 404 means the requestId is not an identification in your account.

Coming from FingerprintJS

FingerprintJS.load() and fp.get() become new TraceTail() and generateFingerprint(). visitorId and requestId keep their names, and confidence.score becomes confidence. The two libraries compute different IDs, so run both side by side for a while to link returning visitors. See TraceTail vs FingerprintJS and FingerprintJS alternatives compared.

Signals

• basic: browser and OS family (without versions), language, platform, cookies enabled, screen size as [long side, short side], color depth and time zone
• hardware: CPU cores, touch points and device memory
• canvas: how the browser renders a reference drawing
• webgl: graphics vendor and renderer
• fonts: which of 24 common fonts are installed
• automation: navigator.webdriver, sent for the API's bot verdict and not part of the visitor ID

The SDK uses no cookies, storage, Web Workers or WebAssembly, and it adds no event listeners.

Pricing and limits

Every account includes 1,000 identification requests a month, with no card required. Add a card in your dashboard to continue past that at $0.10 per 1,000 requests. Each API key can make up to 100 requests per second. Keyless mode never calls the API, so it isn't metered. See pricing.

Privacy and consent

With an API key, TraceTail stores each visitor ID with the collected signals, IP address and user agent for 180 days, and keeps request logs for 90 days. To erase a visitor, send DELETE /api/visitors/:visitorId from a signed-in dashboard session. You are responsible for any consent your visitors' jurisdiction requires. getComplianceContext() returns browser hints (Global Privacy Control, Do Not Track and the region inferred from time zone and language) to help you decide when to ask:

import { getComplianceContext } from '@tracetail/js';

if (!getComplianceContext().likelyRequiresConsent || visitorHasConsented) {
  const { visitorId } = await tracetail.generateFingerprint();
}

AI coding agents

Claude Code, Codex, Cursor and other agents can add TraceTail on their own. Connect the MCP server at https://tracetail.io/mcp (no account or key needed; in Claude Code, claude mcp add --transport http tracetail https://tracetail.io/mcp), install the skill with npx skills add https://tracetail.io, or point the agent at llms.txt. An agent gets the API keys through a setup link: it hands you one link, where you sign in with an emailed code and add a card or continue free, and receives a key for each site.

License

MIT