Tracking
Identify a visitor
Turn an anonymous browser into a named person — from a form the visitor submits or from an identify call of your own.
Every visitor starts anonymous: the script gives the browser an id and ties the visit to it. A visitor becomes a known person the moment Tracking learns an email address or a phone number for them, and from then on the visits before and after that moment belong to one person, on the People page and in the reports.
There are two ways it learns them.
| Way | You do | Use it when |
|---|---|---|
| From a form (Recommended, and automatic) | Nothing at all | Your sign-up, sign-in or contact form is a plain form submit |
From an identify call | Call lt('identify', …) when you learn who the visitor is | A single-page app, a social login, a multi-step flow — anything that is not a plain form submit |
Both are dropped for a visitor in cookieless mode: a declining visitor cannot become a person, by design. See What tracking does with a consent answer.
Identify explicitly
Call it as soon as you know who the visitor is:
lt('identify', 'ada@acme.com');
lt('identify', 'ada@acme.com', { plan: 'pro', signup_source: 'pricing' });The first argument after the command is the email address; the second is an optional object of traits, stored as properties of the event.
The other shape takes an object, and is the one to use when you have a phone number, or both:
lt('identify', { email: 'ada@acme.com' });
lt('identify', { phone: '+15551234567', traits: { plan: 'pro' } });
lt('identify', { email: 'ada@acme.com', phone: '+15551234567' });Only email, phone and traits are read from that object. A call with neither an email nor a phone number is ignored, so there is no harm in calling identify with whatever you happen to have.
Call it again on every page load where the visitor is already signed in. Repeating a known identity costs nothing and makes sure the visitor is recognised even if a cookie was lost.
How the values are read
An email address is trimmed and lower-cased, so Ada@Acme.com and ada@acme.com are the same person.
Phone numbers are accepted conservatively, because a wrongly parsed number would merge two different people. A number in international form — a leading + and 8 to 15 digits — is always accepted. A plain 10- or 11-digit North American number is accepted too. Anything else is ignored, and the event still counts on its other signals. If you have the number in international form, send it that way.
What the form capture reads
The script watches for form submissions on every page it runs on. When a form is sent it looks at the values in that form and takes an email address, a phone number, or both. You do not mark up your forms in any way, and nothing is sent while the visitor is typing — only on submit. Submitting the same form twice in a row records the identity once.
| Field | Read? | Rule |
|---|---|---|
| Yes | Any field whose value looks like one: something, an @, then a dotted domain. The field’s name does not matter. | |
| Phone | Only from a clearly-marked phone field | The name, id or autocomplete hint has to say so — tel, phone or mobile at the start of a word, so user_tel and mobilePhone count but hotel does not — or autocomplete="tel". The value has to be 7 to 15 digits in a phone-shaped format. A field type of tel alone is not enough. |
| Password | Never | Whatever it contains. |
| Hidden | Never | They usually carry your own system ids. |
| Payment and security | Never as a phone number | Card numbers, CVV or CVC codes and one-time codes, recognised from the autocomplete hint (cc-…, one-time-code) and from names containing card, cvv, cvc, csc, cc, otp, passcode or iban. Values with too many digits to be a phone number are rejected too. |
| Empty | Never | A form that yields neither an email nor a phone number records nothing. |
What a person looks like afterwards
The People page lists everyone Tracking has seen. Each row shows the person — their email address, or Anonymous and a short id when there is none yet — their status, when they were first and last seen, and where they came from. You can filter by status and search by email address, exactly or by prefix.
Status is one of three:
| Status | What it means |
|---|---|
Anonymous | Seen, but no email or phone number yet |
Identified | An email address or a phone number is known |
Customer | Revenue has been recorded for them — see Send revenue from your backend |
Opening a person shows their whole journey, newest event first, with the page, the source and the properties of each event — including the events from before they were identified. Beside it are the identity signals held for them (the email addresses, the phone numbers, the advertising click ids and the domains they were seen on), their lifetime value, and, where there is one, the attribution decision for their journey.
MCP. tracking_profiles_list and tracking_profiles_get read the same list and the same person.
Export or delete a person
A person can be exported or deleted from their own page. Deleting removes the person, their identifiers and their events, and it is how you answer a request to erase someone’s data — consent withdrawal on its own does not delete anything already collected.
MCP. tracking_profiles_export and tracking_profiles_delete.
The same person, twice
People do not stay on one device or one identifier.
- Two devices. A visitor who browses on a phone and later signs up on a laptop starts as two anonymous visitors. As soon as the same email address is seen on both they become one person, and the earlier anonymous browsing is part of that person’s journey.
- Two identifiers. Someone who first gives a phone number and later an email address, in either order, stays one person: each new identifier is added to the one already known.
- Two people on one browser. A shared or borrowed browser gives two identities to the same anonymous id. An email address or a phone number is a stronger signal than a shared browser, so the identified people are kept apart rather than folded together on that evidence.
When two records do turn out to be one person, the older record survives with its history now spanning both, and a Customer status is never lost in the process. This happens on its own, on the next event that ties the two together — there is nothing to merge by hand.
An email address or a phone number is read as identity from an identify call and from the lifecycle events sent with an API key. It is never picked up from the properties you attach to an ordinary track call.
Next steps
- Send revenue from your backend: tie money to the person and make them a customer.
- Install the tracking script: carry one identity across several domains you own.
- Read the attribution reports: what a person’s journey was credited to, and why.
- Fix a person who stays anonymous: the checks in the order worth making.