Identify customers
Attach a known person to the current session with clakta.identify(), so journeys follow the customer instead of the browser.
By default Clakta tracks anonymous sessions. clakta.identify() attaches a
known person to the session you already have, so their activity before and after
login belongs to one customer record.
Basic usage
Call it as soon as you know who the visitor is — on login, on signup, or on any page where you already have the user in context:
clakta.identify({
externalId: "user_123",
email: "ada@example.com",
name: "Ada Lovelace",
})Identifiers
At least one of these three is required. Without one, the call is rejected and logged as a warning:
| Field | Use it for |
|---|---|
externalId | The customer's primary key in your own system. The most reliable option. |
claktaCustomerId | An existing Clakta customer id, e.g. cust_1234567890. |
email | The customer's email address, when you have nothing more stable. |
Optional attributes
name and phone are recognised. Phone should be E.164 — +5511999999999.
Anything else you pass is forwarded as a free-form trait:
clakta.identify({
externalId: "user_123",
email: "ada@example.com",
plan: "pro",
signupSource: "referral",
})Prefer externalId over email as the primary identifier. Emails change,
primary keys do not — and a customer who updates their email would otherwise
split into two records.
It only works in full attribution mode
identify() is a no-op in privacy-friendly projects. Nothing is sent and
nothing is stored. It is also a no-op when the visitor has withheld consent.
This is by design: attaching a name to a session is the opposite of anonymous collection, so the mode that promises no personal identification does not make an exception for this call.
If you are calling identify() and seeing nothing in the Users section,
check the project's tracking mode first. With debug: true the SDK logs
Skipping identify (privacy_friendly mode or consent withheld) so you can
confirm it in the console.
See Tracking modes.
Calling it early is safe
identify() is commonly called immediately after init(), while the SDK is
still fetching the project configuration and does not yet know the tracking
mode. The call is buffered and replayed once the mode is known — you do not have
to wait for a ready event.
If the configuration cannot be resolved at all, the buffered call is dropped rather than sent blindly.
Where to call it
- On login — the single most valuable place. It connects the anonymous browsing that preceded the login to the person doing it.
- On signup — the first moment a visitor becomes a customer.
- On any authenticated page load — harmless to repeat, and it recovers sessions that began before your login handler ran.
Repeat calls with the same identifier are safe. Later calls update the traits you send.
Never pass an identifier taken from a URL parameter or an unverified form field. Anything the browser can send, a hostile browser can forge, and you would be merging a stranger's activity into a real customer's record.
Related
Related articles
How Clakta tracking works
The path a visitor takes from an ad click to an attributed order, and which part of the system is responsible for each step.
Tracking modes
Privacy-friendly or full attribution — what each mode collects, how sessions are built in each, and what changes in your data when you switch.
Track ecommerce events
Record product views, add to cart, checkout start and payment submitted from the browser — and understand why completed purchases are not in this list.