Skip to main content
ShieldLabs assigns a stable identity to each visitor from browser, device, and network signals. Every identify call returns a set of identifiers in the webhook and History API. This page explains what each one is, how it is derived, and how long it survives.

​
The four-layer identity model

ShieldLabs organizes identity into four layers, from the most persistent to the most specific:

Visitor

The persistent identity for the same person across sessions and network changes on a given browser. Carried by VisitorID.

Session

The current visit. A short browsing window, carried by SessionID.

Device

The browser environment itself, derived from the fingerprint. Carried by DeviceID, the most durable identifier.

User

The logged-in account, supplied by you as a hashed UserHID. ShieldLabs never derives this.
These layers nest. One DeviceID (a browser) can hold many VisitorIDs (each time cookies are cleared, a new one appears), and any of those can be tied to one or more UserHIDs once a person signs in. That correlation is what powers the abuse patterns on the dashboard.

​
The six identifiers

IDHow it is madePersistence
RequestIDA client-generated UUID, one per identify call. It is the join key across the initial snapshot, the webhook, and the History API.Unique per call.
SessionIDA client UUID stored in sessionStorage, scoped to a roughly 10-minute visit window.Per visit or tab.
CookieIDA first-party UUID minted in the browser (cookie plus localStorage, 2-year cookie).Lost when cookies or site storage are cleared.
DeviceIDServer-derived. A UUID5 hash of dozens of stable browser-fingerprint components (canvas, WebGL, audio, fonts, screen, navigator, timezone, and more).Durable. Survives cookie-clear, incognito, and IP rotation within the same browser. Browser-bound (a different browser is a different DeviceID).
VisitorIDServer-derived. A UUID5 of DeviceID plus CookieID.Changes when cookies are cleared (a new CookieID produces a new VisitorID). Many VisitorIDs can map to one DeviceID.
UserHIDYour own account id, passed into the snippet. Must be hashed or pseudonymous.Whatever you set.
RequestID, SessionID, and CookieID are minted in the browser. DeviceID and VisitorID are computed on the server from the fingerprint, so the browser never sees them. You read them from the webhook (correlated by RequestID) or the History API. All six appear in the webhook body and in History API rows. For the exact field list and JSON shapes, see API models.

​
Why DeviceID is durable

DeviceID is the identifier most analytics tools cannot match, because it is derived, not stored. ShieldLabs computes it server-side as a UUID5 hash over dozens of stable browser-fingerprint components: canvas and WebGL rendering, audio, installed fonts, screen geometry, navigator properties, timezone, and more. Volatile components (such as speech-synthesis voices and storage quota) are deliberately excluded so the hash stays stable. Because the same browser environment always produces the same hash, the DeviceID:
  • Survives a cookie clear. Nothing about it lives in the cookie. Clearing cookies removes the CookieID, not the fingerprint.
  • Survives incognito and private windows. The fingerprint is the same browser on the same machine.
  • Survives IP rotation. Switching networks, using a VPN, or moving between Wi-Fi and cellular does not change the browser fingerprint.
DeviceID is browser-bound. The same person on Chrome and on Firefox produces two different fingerprints, so two different DeviceIDs. ShieldLabs does not do cross-browser recognition today. Counts are best understood as estimated, not exact.
This durability is why the Visitors view can recognize a returning person whose cookies expired, where cookie-based analytics would count them as brand new.

​
Why VisitorID can change

VisitorID is built from two inputs: UUID5(DeviceID + CookieID). The DeviceID half is durable, but the CookieID half is not. So when a visitor clears cookies or site storage:
  1. The CookieID is gone and the browser mints a fresh one on the next visit.
  2. The server combines the same DeviceID with the new CookieID.
  3. The result is a new VisitorID.
That is by design. It means one durable DeviceID can sit behind many VisitorIDs over time. If you need the most stable handle on a returning person within a browser, use DeviceID. Use VisitorID when you want the cookie-scoped view (a specific browser-storage identity), and UserHID when you have a logged-in account.
A burst of new VisitorIDs all mapping to one DeviceID, or one VisitorID appearing across many DeviceIDs, is itself a signal. The dashboard surfaces these as the “Changing IDs on One Account” and “Many Devices on One Visitor” abuse patterns.

​
UserHID must be hashed

UserHID is the only identifier you control. It is your own account or user id, passed into the snippet so ShieldLabs can tie anonymous activity to a known account. Pass a hashed or otherwise pseudonymous value. Apply the same transform every time so the same account always maps to the same UserHID. 
// Hash the user id before passing it to the snippet.
const userHID = await sha256(currentUser.id); // never the raw id or email
const mod = await import('https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY');
mod.checkAuthenticatedUser(userHID);
Never pass a raw email address, username, or primary-key user id as the UserHID. Always hash it (for example SHA-256) or use a pseudonymous token. ShieldLabs stores and echoes the UserHID back in webhooks and History, so a raw value would put plaintext account data in those payloads.
When no user is logged in, use checkAnonymous() instead and the UserHID is left unset. See the snippet setup for the full method list.

​
How the identifiers connect to scoring

The identifiers answer “who is this”. The Risk Score answers “how anonymous or risky is this visit”. They arrive together in the same webhook: the IDs above plus a 0 to 100 Risk Score and the Details that explain it. You decide what to do with that combination in your own code. ShieldLabs surfaces the identity and the signals; allow, challenge, review, or block stays with your application.

Visitors view

See how DeviceID-based identity gives real new-vs-returning counts where cookie analytics inflate them.

Risk Score

The explainable 0 to 100 score and its bands: Clean, Low, Medium, High.