Identity · Amplitude learning guide

By the end of this chapter

You will know what device_id, user_id and Amplitude ID are and who creates them.
You can follow a merge step by step.
You will recognise the user_id mistakes that turn thousands of people into a single user.

Three identities

Identity	Created by	Exists from	Represents
`device_id`	The SDK (per device or browser)	First open, even before login	A device or browser
`user_id`	You, from your customer system	When the user logs in and you set it	A customer account
Amplitude ID	Amplitude, by matching the two	Always	The "person" counted in analysis

On the Adjust side

In Adjust, an ADID represents one device in one app and there is no cross-device merging: the same person's phone and tablet are two installs. In Amplitude the same person is one user as long as they log in with the same user_id. User counts in the two tools are structurally different for this reason.

Walk through a merge

In the scenario below a customer first uses the app on a phone, then on a tablet. Step through it to see which event belongs to which Amplitude ID.

Event	Device	device_id	user_id	Amplitude ID

Sample IDs for illustration. Amplitude IDs in the same colour are the same person; highlighted rows are the ones affected in that step.

Merge rules

Anonymous → identified: events from before login on a device are attached to the person when user_id is set on that same device. This is why onboarding can be measured before login.
Across devices: when the same user_id appears on different devices, those devices merge into one person.
Two different user_ids don't merge: logging in with a different user_id on the same device is treated as a new person. The problem is who the anonymous events between logins get written to.

Verify

The exact merge rules (especially what happens when the user changes on the same device, how "new user" counts before a merge look retroactively, and whether a wrong merge can be undone) are described in Amplitude's identity documentation. Check there before making a definite statement to a client.

Devices, people, logins: one audience, three numbers

Counting the same week of an app in three different units gives three different numbers. Which one is "right" depends on the question.

Sample data. Device count is highest because one person can have several devices. Amplitude user count is the number of people after merging. Logged-in users are the subset with a user_id set.

Expensive mistakes

Identity mistakes are silent: events keep arriving, charts fill up, but numbers get written to the wrong people. The most common ones:

Don't

Shared values like setUserId('guest'), '0', 'null', 'undefined': everyone merges into one person
Using an email address as user_id: it can change and it is personal data
Setting a temporary ID before login and then switching to the real one
Not resetting identity on logout
Different ID formats on iOS and Android (88231 vs cust_88231)

Do

Use the stable, unique customer ID from the backend
Don't set user_id until the user has actually logged in
Call the SDK's reset function on logout
Use the same ID format on every platform and in the HTTP API
Check a few test users in user lookup before release

Why it's expensive

In most cases a merge cannot be fixed retroactively. The history of thousands of people merged under 'guest' stays as one "super user", and retention, funnel and user counts for that period become unreliable.

Verify

Amplitude may block some obviously invalid ID values and applies a minimum length rule to user_id / device_id. Check the current list and rule in the HTTP API documentation.

Logout example

Browser SDK (JavaScript), logout on shared devices

import * as amplitude from '@amplitude/analytics-browser';

// On login: link this device to the backend customer ID
amplitude.setUserId('cust_88231');

// On logout: clear user_id and start a fresh device_id,
// so the next person's events are not written to this user
amplitude.reset();

A "new user" is not an install

In Amplitude a new user is the moment an Amplitude ID is first seen. In Adjust an install is a device's first session. The two numbers diverge in these cases:

Situation	Adjust	Amplitude
Person installs on a second device and logs in	New install	Merged, same person
Person used the web first, then installed the app (same user_id)	New install	Existing user
Amplitude SDK starts after consent, user declined	Per its own consent rules	Never seen
Amplitude SDK starts after the first screen, user left immediately	Install	Never seen

Chapter 7 shows how to break these differences down in a discrepancy analysis.

Exercise

In a test project, log in with the same user_id from a normal browser window and then from a private window. In user lookup, see the two devices merge into one user. Then log in with a different test account without calling reset() on logout and check who the events in between were written to.