Visitor identification

Every visitor starts anonymous. When someone signs up or logs in, tell Statsy who they are and their whole journey on this browser, before and after, is shown under that name. Identifying also lets a payment be matched by email when a checkout carried no visitor id.

statsy.identify('user_8f3a', {
  email: 'ada@example.com',
  name: 'Ada Lovelace',
  plan: 'pro',
  company: 'Analytical Engines Ltd',
});

The first argument is your own stable user id. Use the database id, never the email, so a changed address does not become a second person. The traits object is optional; the older form statsy.identify({ email }) still works.

When to call it

• Right after a signup or login completes, on the page the user lands on.
• On every page load of the signed-in app. It is idempotent and cheap: same id, same traits, nothing changes.
• When a trait changes that you want on the profile, such as a plan upgrade.

What is stored

Up to 16 traits of at most 200 characters each, 4 KB in total, against the visitor id for that site, in your workspace's database rather than the analytics events. The reserved traits are email and name, shown in the dashboard, and id, the first argument. Everything else is kept as is and shown on the visitor's profile.

Watch out. Never put passwords, card numbers, government ids or health details in traits. Identification is for who someone is to your product, not for everything you know about them.

Where it shows

• Journeys: the visitor list is searchable by email, name or id, and each journey is headed by the identity.
• Live: identified visitors carry their name instead of a location-only label.
• Revenue › Customers: a paying customer is an identity with payments, with lifetime value and first touch.
• Public share links never show identities. The share API leaves the fields out entirely.

From anonymous to known

Identification attaches to the browser's visitor id, so everything that id did earlier is now this person's history. This works in full mode, where a visitor id exists. A cookieless visitor has a key that changes daily and cannot be linked to a person, so identify() is recorded for the day but cannot reach back to earlier days. Sites that need this call statsy.consent('granted') after login, which switches that browser to full mode.

Matching payments by email

A webhook payment that arrives without a visitor id is matched to an identified visitor with the same email, first claimant wins, so a later identify() with someone else's address cannot take over their revenue. See how revenue attribution works.

Removing a person

A deletion request is one call: DELETE /api/v1/sites/:site/data?visitor=ID removes that visitor's events, sessions, heatmap hits, identity and payments, or use Site settings › Danger zone › Delete one visitor. The visitor id is on their journey page and is returned by statsy.visitorId() in the browser. See Deleting data.

Frequently asked questions