For the complete documentation index, see llms.txt. This page is also available as Markdown.

Resolve identities

Improve how many of your users are recognised as one person, and repair links that are wrong.

Your goal

Increase the share of your data that lands on a single UserPoint per real person - by collecting the right identifiers at the right moment, and by declaring the links the platform cannot infer on its own.

Expected outcome

Fewer UserPoints per real user, more complete histories, and no ordinary user flagged as a hyper point.

What resolution the platform does by itself

Automatic identity resolution merges two UserPoints when it learns they represent the same person. It happens on its own, and it can only be triggered by two things:

  • UserActivity updates - an activity arriving with more than one identifier, one of which is already known on another UserPoint.

  • User identifier association declarations - you telling the platform explicitly that identifiers belong together.

The mechanics, and what a merge does to your data, are in UserPoint & Identity graph.

What you can do to improve it

1

Send every identifier you have, on every activity

Resolution only happens when identifiers meet. An activity that carries a device identifier and an account ID is what joins the anonymous history to the known customer; an activity that carries only one of them never will.

Send them together in the $user_identifiers list. See User identifiers.

2

Collect a person-level identifier as early as you can

A device identifier only ever identifies a device. Recognition across devices requires an account ID or an email hash, so the earlier in the journey you capture one, the more history consolidates.

3

Hash emails identically everywhere

A hash produced by a different function is a different identifier and will never match. Agree the function once per datamart, and apply it in every integration.

4

Your own systems often know that two identifiers belong to the same person - a CRM that stores both a hashed email and an account ID, for example. You can declare those associations in bulk, and each declaration creates or merges a UserPoint holding all the identifiers on the line.

Any combination of identifier types can be declared together: email hashes, user agents, and account IDs.

Association declarations are only supported for datamarts using a UserPoint system version of v201812 or later.

The import format and worked commands are in Enrich users with identifiers.

5

Add network IDs where your own identifiers run out

Network IDs recognise users in environments where your identifiers do not reach. Note the trade-off: a probabilistic ID increases reach but is not allowed to merge device points or UserPoints.

What you cannot undo

The same caution applies to shared identifiers: a household device, a shared account, or a shop tablet will consolidate several real people into one UserPoint if it is treated as a strong identifier.

What to watch

Signal
What it tells you
Where

UserPoint volume growing faster than your real user base

Identifiers are being minted rather than matched - a format problem, or a missing registry.

Ordinary users flagged as hyper points

Too many identifiers accumulating on one UserPoint: more than 10 per registry ID in 2 days, more than 4 account IDs or email hashes in 7 days, more than 8 merges in 14 days, or more than 100 identifiers in total.

Users in quarantine

More than 10,000 activities or 5,000 segments on one UserPoint - usually over-consolidation, or retention that is too long.

A known test user split across UserPoints

An identifier is not being sent where you assumed it was.

Verify

  • A test user logging in on two devices consolidates into one UserPoint.

  • Association declarations produce the number of merges you expected, not several times more.

  • Segment metrics counting accounts and emails move in the direction you expect after an improvement.

  • No ordinary user is flagged as a hyper point or quarantined.

Last updated

Was this helpful?