Identity
install_id, user_id and how they turn into people in reports.
Every event carries an install_id, the installation identifier, and, if the user is signed in, a
user_id, the identifier of their account. By default, reports count people, not devices: several
installations of one account are one person.
install_id
A UUID that the app generates once on first launch and keeps permanently. Any UUID version works
except the nil UUID 00000000-0000-0000-0000-000000000000; we recommend a lowercase UUIDv4.
| Platform | Where to store it | Survives a reinstall |
|---|---|---|
| iOS, macOS | Keychain | Yes |
| Android | SharedPreferences with Auto Backup | Yes, if backup is enabled |
| Web | localStorage | No: clearing site data means a new installation |
| Bot | Derived from the chat ID via HMAC | Yes |
| Backend | Configuration or database | Yes |
If the install_id is lost, the user looks new and retention comes out lower than it is. Don't
generate a new install_id on every launch.
user_id
An opaque account ID from your app's backend: a primary key, a UUID, an internal number. Length: 1 to
128 characters. Send user_id with every event while the user is signed in, and stop sending it after
they sign out.
The server rejects a user_id that looks like an email address or a phone number with the code
user_id_looks_like_pii. Purely numeric strings are allowed, but Telegram IDs and other public
numbers are better hashed on your side — see
Bots and backends.
How people are counted
Merging happens when a report is built; raw events are never rewritten:
- An event with a
user_idbelongs to the personu:<user_id>. - Anonymous events of an installation belong to its "first owner": the user from the earliest event
of that installation that has a
user_id. The days before sign-in are attributed to that user retroactively. - An installation where nobody ever signed in is a separate person
i:<install_id>.
Example: installation I1 ran anonymously for three days, and on the fourth day the user signed in
as A. All four days count as one active person u:A, who became new on the first day, not on the
day of sign-in.
If two accounts signed in on the same device, anonymous events go to the first of them, and events
with an explicit user_id go to their own account.
People on multiple platforms
An app unites all of its platforms, and merging works across them: a user who signed in as A on iOS
and on the web is one person u:A. That's why aggregated reports count people rather than adding up
platforms. Only user_id merges people: anonymous installations on different platforms stay
different people, so send the same user_id everywhere the user is signed in.
The platform switcher above the reports keeps only one platform's events. A person active on iOS and on the web is counted in each of them, so the sum across platforms can exceed the total. Platform shares in the portfolio are counted the same way.
If the platforms of one product are connected as separate apps, people aren't merged between them. Merge such apps in the settings — see Merging apps.
persons and installs
Reports and the Read API accept a unit parameter:
persons(default) — people, according to the rules above;installs— each installation on its own, as in AppMetrica. Use this mode to reconcile numbers with AppMetrica.
A person's profile is opened by person_key: u:<user_id> or i:<install_id>. A colon is allowed
in the URL, and a / inside user_id is encoded as %2F.