Identifying people
How identify() ties sessions and problems to a person and an account, what is stored, how anonymous sessions work, and how to identify requests on the server.
This page is for whoever wires Sypnia to an app’s sign-in. identify() is the same call in @sypnia/browser, @sypnia/next and @sypnia/node, and it works the same for the open-source engine and for Sypnia Cloud.
At the end you will have: problems that say who they hit («3 people», and which three), sessions you can find by person, and activity for each person and each account.
The call
import { identify } from '@sypnia/browser';
// when someone signs in, and when the app loads with someone already signed in
identify({
person: { id: 'u_1042', name: 'Ada Park', email: 'ada@example.com' },
account: { id: 'acc_77', name: 'Corner Café' },
});
// when they sign out
identify(null);| Field | Type | Required | Limit | Meaning |
|---|---|---|---|---|
person.id | string | yes | 1 to 128 characters | The person’s id in your app. Sypnia treats it as an opaque string: a number as text, a UUID, anything stable. |
person.name | string | no | 120 characters | Shown next to the person. Personal data. |
person.email | string | no | 254 characters | Shown next to the person, and searchable. Personal data. |
account.id | string | no (yes if you pass account) | 1 to 128 characters | The id of the account the person belongs to in your app: a team, a company, a club, a shop. |
account.name | string | no | 120 characters | Shown next to the account. |
Use the id your database uses, not the e-mail: an e-mail changes, and it would put personal data into every event. An id that is not a string is turned into one. An empty or missing person.id makes the call do nothing, with one warning.
What happens after the call
- The SDK sends one
identifyevent with the person and the account as you gave them. It is the only event that carries a name or an e-mail. - Every later event of the session carries the two ids only:
"person": {"id": "u_1042"},"account": {"id": "acc_77"}. - The session, including what happened in it before the call, belongs to that person. Someone who browses, then signs in, has one session.
- The SDK remembers the ids for the life of the page only. It does not store them in the browser: call
identify()again on every page load where someone is signed in.
Calling it again with the same person is free: nothing is sent unless the name, the e-mail or the account changed.
Sessions and people
| Situation | What Sypnia does |
|---|---|
| Nobody identified | The session is anonymous. It is listed, counted and replayable like any other. |
Anonymous, then identify(A) | The same session, now A’s. |
identify(A), then identify(null) | A’s session ends. The next activity starts a new, anonymous session. |
identify(A), then identify(B) | A’s session ends. B’s first activity starts a new session. |
| The same person on a phone and a laptop | Two sessions, one person. |
When Sypnia says «3 people», it counts identified persons, plus one for each device whose sessions were never identified.
On the server
Requests that come from an identified browser session need nothing: the browser SDK sends the session’s id with each call to your API, and Sypnia takes the person from the session.
Identify on the server only what no browser session identifies: calls from a mobile app, from an API client, from a webhook.
import { identify } from '@sypnia/node';
app.use((req, res, next) => {
if (req.user) identify({ person: { id: req.user.id }, account: { id: req.user.accountId } });
next();
});On the server identify() applies to the request being handled and to nothing else. Names and e-mails passed here are stored the same way as from the browser.
Backends that report through OpenTelemetry cannot identify people at launch: their traces get the person from the session.
Personal data: what you decide
person.id and account.id are the only things Sypnia needs. With ids alone, Sypnia holds no name and no e-mail, and you look people up in your own system.
If you send names and e-mails:
- They are stored with the person, shown in the app and the Console, returned by the API, and searchable.
- They are listed as personal data in What is collected.
- The agent uses counts of people, not their names. See Models and what is sent.
- You can delete one person and everything tied to them. See Deleting data.
Sending a new name or e-mail for the same person.id replaces the old one.
Always record someone
To record every session of one person or one account, for example a customer who reports a bug you cannot reproduce, add an «always record» rule to the project. It is a project setting, not code, so it takes effect at that person’s next session without a deploy. See Sampling and quotas.
Who may send an identity
At launch the ingest key is the only credential for sending, as with any browser SDK. It is public, so Sypnia cannot prove that an event saying «I am u_1042» comes from u_1042’s browser: someone who reads your page’s source could send events with any id. They could not read anything, and limits per key and allowed origins bound what they can send. Do not use Sypnia’s person data as proof of who did something.
A signed identity, for apps that need that proof, is Planned.
Check that it works
- Set
debug: true, sign in to your app, and look at the console: oneidentifyevent, then events carryingperson: { id: … }. - Within 10 minutes the session in Sypnia shows the person’s name, or their id if you sent no name.
Next
- What a session is and who it belongs to.
- What leaves the browser, and what never does.
- Remove one person’s data.