Identity stitching

Stitching guide

How GetFluxly turns three kinds of ID into one unified profile, plus the conflict-resolution rules.

The authoritative version is in docs/sdk-standards/identity-stitching.md. This page is the developer-facing summary.

The algorithm in one paragraph

When an event arrives, the identity worker looks at every ID present (anonymous_id, external_id, user_id) and finds existing profiles that match any of them. If exactly one matches, the event joins that profile and any new IDs get attached. If two or more match, they're merged into the oldest profile and the rest are tombstoned. If none match, a new profile is created.

Why explicit `identify` matters

Without an identify call linking an anonymous_id to an external_id, the worker has no way to know they're the same person. It will create two profiles: one indexed by the anonymous ID, one by the external ID. The events split between them.

The SDKs handle the link as soon as you call identify(...). If you're integrating directly against the REST API, include both IDs in the first server-side event after sign-in.

Merging rules

When two profiles need to merge:

The older created_at wins, that profile survives.
Both profiles' events are remapped to the survivor.
The survivor's traits are kept; only missing trait keys are filled in from the dying profile.
The dying profile gets merged_into = <surviving_id> and is excluded from queries.

What you should never do

Don't reuse anonymous_id across users. That ID is per-device, per-browser-storage-clear. Treat it as ephemeral.
Don't call identify with a different external_id than the one tied to the current session. Use alias for ID swaps.
Don't put PII in anonymous_id. It ends up in URL fragments, cookies, and analytics tools. Use random opaque strings.

When the result looks wrong