Browser agent

The agent collects device signals in the browser and sends them to the API, which stores an event and answers with the visitor's visitorId and the event's requestId. Its report is about a kilobyte.

Install

There are two ways in: the hosted script to try things, and the npm package through your own domain for production.

Try it: the hosted script

The quickest way is the hosted script: it serves the agent from the agent's origin and exposes start on the global FingerprintAgent. It works the same on a static site (Netlify, Vercel, S3, GitHub Pages): nothing runs on your server. It always loads from the API's own domain, so content blockers that list that domain stop it; use it to try things, not on a live site.

<script src="https://zenocdn.net/agent.js"></script>
<script>
	const agent = FingerprintAgent.start({ endpoint: 'https://zenocdn.net', publicKey: 'pk_...' })
</script>

For production: npm and your own domain

For a live site, install zeno-id and serve the agent from your own domain: a custom domain, a subdomain of your site you add in Settings › Custom domain with one DNS record. The package is a small typed loader, not the agent itself: when the page runs, start() fetches the current agent from your endpoint, so bundling it into your app doesn't freeze an old version, and our fixes reach your visitors within the hour the agent is cached for.

bun add zeno-id

import { AgentError, start, type AgentErrorCode } from 'zeno-id'

// Your custom domain; the agent's own origin when left out.
const agent = start({ publicKey: 'pk_...', endpoint: 'https://metrics.example.com' })

Name the subdomain something plain, never with fp or fingerprint in it; Choose a subdomain says why.

Start

start() begins collecting right away and returns an agent. Call it once per page load, early, like when a login form opens; one agent serves every later get().

const agent = start({
	publicKey: 'pk_...',
	endpoint: 'https://metrics.example.com',
	cache: { storage: 'sessionStorage', ttl: 60 },
})

A cached result is the same requestId, so it gets older while it's reused. Keep the ttl well under the age your server accepts (the quickstart refuses events older than 5 minutes), like 60 seconds. The cache key holds the external ID, so another user on the same browser identifies afresh; for a get() that must never be cached, like a payment, use a second agent started without cache.

Identify

const result = await agent.get({ externalId: user.id, action: 'login' })

if (!result.capped) {
	const { requestId, visitorId, returning } = result
}

The result holds requestId (the event's id), visitorId and returning (whether the project had seen this visitor before). Send the requestId to your server and read the event there; flags never come back to the browser. In zero trust mode the result has only the requestId, and with sealed results on it also has a sealedResult for your server to open. A capped identification resolves { capped: true } instead.

The agent also sends the page url and referrer without their query string and fragment, which events keep as origin and path, as the origin only or not at all, as the project's settings say. It hashes the request body itself for the x-amz-content-sha256 header the hosted API requires.

The socket proof

While it collects, the agent also opens a WebSocket (a connection that stays open, unlike a plain request) to the endpoint's origin (the agent's own or your custom domain), wss://…/ws, and sends back a challenge the API writes to it, as proof that a browser and not a plain HTTP client is identifying; see the socket proof. A page with a Content Security Policy needs the endpoint's host for both the request and the socket in connect-src, like connect-src 'self' https://metrics.example.com wss://metrics.example.com (or https://zenocdn.net wss://zenocdn.net for the API's own origin), or the socket fails and the events go without the proof. The npm loader also needs the agent's source in script-src, and the agent's worker check worker-src blob:; Content Security Policy has the lines for a custom domain.

The persistent visitor id

The visitor id is kept in localStorage (fp:visitor:<public key>) and a first-party cookie (_fpvid_ and the key's last 8 characters) and sent back on the next identification. Both are per public key, so two projects on one site never hand each other their ids. The service reuses the stored id while the device's hardware still matches, so it survives browser updates that shift canvas or audio output, and can't be copied to another device.

Stop and forget

agent.stop() ends an agent for good, as when a visitor withdraws consent: a get() in progress and every later one reject with agent_stopped, nothing more is collected or sent, the socket closes, and the visitor id and cached results stored for its public key are removed (another project's stay). An agent still loading from npm never starts. forget({ publicKey }), exported by the npm package and on the script's FingerprintAgent global, removes the same entries without starting anything. Call start() again to identify afterwards. Privacy and consent shows both in a consent integration.

Single page apps

In React, Vue, Svelte or any other SPA:

• Start once, in a module, not in a component: a component re-renders and remounts, and each start() collects again.
• Call get() in the handler of the action you protect (the login or signup submit), not in an effect. React's StrictMode runs effects twice in development, and two concurrent get() calls make two events, both billed. If it has to be an effect, guard it with a ref.
• One agent, many get() calls: after the first, a get() is mostly the network round trip.

// src/fingerprint.ts: one agent for the whole app. start() collects the
// signals once; every get() reuses them.
import { AgentError, start } from 'zeno-id'

export const agent = start({ publicKey: 'pk_...', endpoint: 'https://metrics.example.com' })

// The requestId to send to your server, or undefined when nothing was
// identified (capped, blocked, timed out): the server challenges those.
export const identify = async (options: { externalId?: string; action?: string }) => {
	try {
		const result = await agent.get(options)
		return result.capped ? undefined : result.requestId
	} catch (error) {
		if (error instanceof AgentError) {
			console.warn('Identification failed', error.code, error.message)
			return undefined
		}

		throw error
	}
}

import { identify } from './fingerprint'

const onSubmit = async (event: React.FormEvent<HTMLFormElement>) => {
	event.preventDefault()
	const user = await logIn(email, password)
	const requestId = await identify({ externalId: user.id, action: 'login' })

	await fetch('/api/login/verify', {
		method: 'POST',
		headers: { 'Content-Type': 'application/json' },
		body: JSON.stringify({ requestId }),
	})
}

With server-side rendering, create the agent on first use in the browser:

// Next.js, Nuxt, SvelteKit: start() reads browser APIs, so create the agent
// on first use in the browser, never while the server renders.
import { start } from 'zeno-id'

let agent: ReturnType<typeof start> | undefined

export const getAgent = () => (agent ??= start({ publicKey: 'pk_...', endpoint: 'https://metrics.example.com' }))

Local development

• Your custom domain works from your dev server as it is; add the dev server's origin to the allowed origins.
• Allowed origins: add your dev server's origin; see Allowed origins.
• Secure context: the agent needs https, or localhost and 127.0.0.1. A LAN address over http, like the http://192.168.1.20:5173 Vite prints for testing on a phone, fails with insecure_context. Use https there (@vitejs/plugin-basic-ssl, or a tunnel like cloudflared tunnel --url http://localhost:5173).
• No code yet: the /demo page runs the agent on a bare page.

Errors

start() throws, and get() rejects with, an AgentError whose code tells you what happened and whose message says what to change. From npm, check for it with instanceof; the script tag build has only start and forget on its global, so check error.code there.

import { AgentError } from 'zeno-id'

try {
	const result = await agent.get({ externalId: user.id })
} catch (error) {
	if (error instanceof AgentError && error.code === 'origin_not_allowed') {
		// error.message names the origin to add in Settings.
	}
}

Which code you get when

<script src="https://zenocdn.net/agent.js"></script>
<script>
	// Blocked script: no agent, so no request ID; the server challenges.
	const agent = typeof FingerprintAgent === 'undefined' ? undefined : FingerprintAgent.start({ publicKey: 'pk_...' })
</script>

Every get() that comes back with a fresh requestId (not one from the cache) made an event and is billed, the ones whose answer your code ignores too. Don't call it on every page view unless you mean to.

What it collects

• Rendering: canvas (marked as randomized when two identical drawings differ), WebGL vendor, renderer, extensions and parameters, the WebGPU adapter, and audio from a compressed oscillator.
• Device: screen size, color depth, pixel ratio, CPU cores, memory, touch support, platform, architecture, client hints, installed fonts, plugins, speech voices and a math fingerprint.
• Settings: time zone, languages, calendar, media preferences, storage support and quota, permission states, WebRTC support, Apple Pay and Private Click Measurement.
• Integrity: automation leftovers, ad blocker baits, browser functions replaced by script, and navigator values that differ between the page, a worker and an iframe.
• With the request: the page url and referrer without their query string and fragment, the user agent, and the IP address the API sees.

It gathers no network addresses through WebRTC.

Privacy and consent

start() reads the device as soon as it's called. Where you rely on your visitors' consent, start the agent only once they've given it, and identify on the actions you protect rather than on every page view: Privacy and consent shows both, with what to put in your privacy policy.