Identify users

Every visitor starts out anonymous. Spreelytics knows them by a random visitor id kept in their browser, not by who they are. When someone signs up or logs in, call Spreelytics.identify() with their email address. Spreelytics links that browser to a person, and from then on everything the person does, on every device you identify them on, comes together on one profile.

You do not have to identify anyone. Every report works on anonymous visitors. Identifying adds a name to the history, joins a person's devices, and lets you group people by details such as their company.

Call identify

Pass the person's email address:

Spreelytics.identify("ada@example.com");

You can save details about them in the same call:

Spreelytics.identify("ada@example.com", {
  first_name: "Ada",
  last_name: "Lovelace",
  company: "Example Ltd",
});

What to know about the call:

• It takes an email address, and only an email address. There is no form that takes a user id or a username. The address must look like name@domain.tld, with no spaces. Anything else is skipped without a word: no request is sent and no error is thrown. Add debug: true to Spreelytics.init() and the browser console says "Identify skipped: invalid email format".
• Send the address in lower case. Spreelytics stores addresses in lower case, but it looks for an existing person using the exact text you send. A capitalised address such as Ada@Example.com can miss the person saved as ada@example.com and start a second profile. Passing email.trim().toLowerCase() avoids that.
• Call it after Spreelytics.init(). A call made before init() is dropped.
• It returns a promise once the script has loaded. await Spreelytics.identify(...) waits until the request has been answered. A call made while the script is still loading is queued, and returns nothing to wait on.
• It survives a redirect. The request is allowed to finish after the page is gone, so you can identify someone and send them to the next page straight away.
• It is processed in the background, so the person can take a few moments to appear in the app.

When to call it

• Right after signup, as soon as you have the address.
• On every login.
• When your app loads for someone who is already signed in. Identifying the same person again is harmless: it finds the profile they already have. It also catches people who were signed in before you added the call.

The earlier you identify, the more of a person's history is linked to them by name, which matters most on a cookieless audience.

What happens when you identify someone

1. Spreelytics finds or creates the person. It looks for a person with that address in this audience and creates one if there is none. People belong to one audience, so the same address on two audiences is two separate profiles.
2. The browser is linked to the person. The visitor id stored in that browser now points at them.
3. Their anonymous history joins them. Everything that browser did before it was identified now belongs to the person: earlier sessions and events show on their profile, and count for them in goals, funnels and segments.
4. Devices merge. When you identify the same address on their phone or a second computer, that device is linked to the same person, and the profile shows both histories together.

A browser belongs to one person at a time. If a second person signs in on the same browser and you identify them without calling reset() in between, the browser is moved over to the second person. Call reset() when someone logs out, so the next person on that computer starts fresh.

Visitors and people are counted differently

Identifying someone joins their history, but it does not merge visitor counts. The Visitors number on the Overview counts browsers, so one person who visits from a phone and a laptop is still two visitors there, identified or not. Numbers that count people, such as goal conversions, count an identified person once however many devices they use. See Definitions for each unit.

Save details about the person

The second argument of identify() saves details on the person. These are the keys Spreelytics uses:

You use them in two places: the Contact rules of a segment, and in the report builder under Filter → Profile. The profile page itself does not list them. Its header shows the email address, the person id and where their latest visit came from.

city, state and country are whatever you send, as the person told you, for example "United Kingdom". They are separate from the Country, Region and City of their visits, which come from where each visit was made.

The rules for values:

• Values must be strings. A number or a true or false under one of these keys is not saved.
• Each value can be up to 255 characters, and lang must be exactly two characters. A value that breaks either rule makes the whole update fail, so none of the fields in that call are saved.
• Values are trimmed of spaces at both ends.
• An empty string clears a field. null is ignored, and the field keeps its value.
• Other keys are not saved. Spreelytics has no place to define extra fields, so a key outside this table is dropped.

Update details later

Call identify() again with the same address and the new values. Only the keys you send change. The rest keep the values they had.

Spreelytics.identify("ada@example.com", { company: "Analytical Engines Ltd" });

When the change happens alongside something worth recording, you can save it with the event instead, using the third argument of track(). It takes the same keys and follows the same rules:

Spreelytics.track("company_changed", { source: "settings" }, { company: "Analytical Engines Ltd" });

That third argument only works once the visitor has been identified. Sent from an anonymous visitor, the details are dropped and only the event is recorded. See Track events.

Log people out with reset()

When someone logs out, call:

Spreelytics.reset();

What it does:

• Gives the browser a new visitor id. Whatever happens next is recorded as a new anonymous visitor, not as the person who logged out.
• Starts a new session for that new visitor.
• Records a pageview of the current page straight away, as that new visitor's first page.

Nothing already recorded changes: the person keeps their history, and the old visitor id stays linked to them. reset() returns a promise, but the parts that matter happen at once, so you can redirect straight after calling it.

On a cookieless audience, reset() cannot give the browser a new identity, because the browser stores nothing and the visitor is worked out from each request. Until the day changes, that browser is still linked to the person who logged out.

Where identified people appear

• Profiles, on the Identified tab. The email address is the profile's name, with a tick whose tooltip reads "Identified visitor". The note at the top of the page, "If you haven't called identify, your profiles will stay anonymous.", is there for the case where nobody has been.
• A person's profile page. The header shows their first email address as the name, a tick, and under it "Identified person", or "Customer" once they have paid. The Person ID and Emails rows sit beside it, and the sessions and timeline below cover every device linked to them. See Profiles.
• Sessions. An identified visit shows the person's address with a tick, and links to their profile.
• Segments. The Identity rules Email and Identified pick people by address or by whether they are identified at all, next to the Contact rules for the fields above.

On a cookieless audience

With cookieless tracking on, the browser stores nothing, so an anonymous visitor can only be recognised within one UTC day. Identifying still joins a person across days and devices from the moment you call it. What it cannot do is reach backwards: each earlier day had its own anonymous visitor id, and nothing links those days to the person. Identify people as early as you can, for example every time your app loads for a signed-in user.

Related

• Track events: send what people do, and update their details as you go.
• Segments: group people by the details you save here.
• Profiles: read one person's full history.
• Cookieless tracking: what changes when the browser stores nothing.