Link anonymous → known users

Stitching pre-login activity to the post-login user, including multi-device.

A visitor lands from a Facebook ad on Tuesday. Browses for a week. Signs up on the following Monday. You want to credit that signup to the original Facebook click — and to know all the things they did before signing in.

This is the canonical "anonymous-to-known" stitch.

What's happening under the hood

Day 1 14:00  $pageview        anon=u_abc  user=NULL    source=facebook/paid
Day 1 14:02  clicked_pricing  anon=u_abc  user=NULL    source=facebook/paid
Day 5 09:30  $pageview        anon=u_abc  user=NULL    source=direct/direct
Day 7 11:14  $identify        anon=u_abc  user=user_42                 ← here
Day 7 11:14  signup           anon=u_abc  user=user_42
Day 9 16:22  feature_used     anon=u_abc  user=user_42

anonymous_id is the same throughout. user_id only appears from the $identify onward. Historical events for u_abc aren't rewritten — they remain user_id = NULL. Stitching is a query-time join.

The single most important moment.

From the browser

import { identify } from "@millimetric/track";

// after your auth flow resolves
identify(user.id, { email: user.email, plan: user.plan });

The browser SDK emits a $identify event and tags every subsequent track() with user_id.

From the server (recommended for signups)

When the user is created in your DB, also POST identify:

import { init, flush } from "@millimetric/track-node";

await fetch(`${process.env.AOA_HOST}/v1/identify`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AOA_SK}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    anonymous_id: req.cookies.aid,           // threaded from the browser
    user_id: createdUser.id,
    traits: { plan: createdUser.plan, email: createdUser.email }
  })
});

(See Server-side events for how to thread anonymous_id.)

After identify, the browser SDK keeps the same anonymous_id. Don't generate a new one — that breaks the link.

For server-rendered apps, persist the id in a first-party cookie (see server-side recipe) so it survives logout/login on the same device.

Step 3 — stitch in queries

Three increasingly thorough patterns.

3a. First-touch source per user

For "where did user_42 come from?" — find the earliest event for any anonymous_id they've ever been associated with.

WITH user_anons AS (
  SELECT DISTINCT user_id, anonymous_id
  FROM events
  WHERE project_id = '...'
    AND user_id IS NOT NULL
)
SELECT
  u.user_id,
  argMin(e.source, e.timestamp)   AS first_touch_source,
  argMin(e.medium, e.timestamp)   AS first_touch_medium,
  min(e.timestamp)                AS first_seen_at
FROM events e
JOIN user_anons u USING (project_id, anonymous_id)
WHERE e.project_id = '...'
GROUP BY u.user_id;

This works for multi-device users too — every device's anonymous_id is in user_anons because they all eventually called identify.

What was user_42 doing before they signed up?

WITH their_anons AS (
  SELECT DISTINCT anonymous_id
  FROM events
  WHERE project_id = '...' AND user_id = 'user_42'
)
SELECT
  timestamp,
  event_name,
  source,
  medium,
  path,
  JSONExtractString(properties, 'utm_campaign') AS campaign
FROM events
WHERE project_id = '...'
  AND anonymous_id IN (SELECT anonymous_id FROM their_anons)
  AND user_id IS NULL                      -- only the pre-identify ones
ORDER BY timestamp;

3c. Time-to-conversion per user

WITH stitched AS (
  SELECT
    u.user_id,
    min(e.timestamp) AS first_seen,
    minIf(e.timestamp, e.event_name = 'signup') AS signed_up_at,
    minIf(e.timestamp, e.event_name = 'completed_checkout') AS first_purchase_at
  FROM events e
  JOIN (
    SELECT DISTINCT user_id, anonymous_id
    FROM events
    WHERE project_id = '...' AND user_id IS NOT NULL
  ) u USING (project_id, anonymous_id)
  WHERE e.project_id = '...'
  GROUP BY u.user_id
)
SELECT
  user_id,
  first_seen,
  signed_up_at,
  dateDiff('hour', first_seen, signed_up_at)        AS hours_to_signup,
  dateDiff('day',  signed_up_at, first_purchase_at) AS days_to_first_purchase
FROM stitched
WHERE signed_up_at IS NOT NULL;

Multi-device

Every device the user signs in on emits its own $identify, linking that device's anonymous_id to user_id. The "anonymous_id ↔ user_id" relation becomes many-to-one over time, which is exactly what you want.

SELECT
  user_id,
  groupArray(DISTINCT anonymous_id) AS devices,
  count(DISTINCT anonymous_id) AS device_count
FROM events
WHERE project_id = '...'
  AND user_id IS NOT NULL
  AND timestamp > now() - INTERVAL 90 DAY
GROUP BY user_id
HAVING device_count > 1
ORDER BY device_count DESC;

When NOT to call identify

Moment

Identify?

Anonymous browsing

User signs up (creates account)

yes

User logs in (returning)

yes — confirms link on this device

User logs out

no — keep tracking events anonymously, but don't reset anonymous_id

User switches account

yes — call identify with the new user_id

Calling identify on every page is fine. It's idempotent at the data level — you'll just have more $identify events.

Common pitfalls

Generating a new anonymous_id on logout. Severs the link. Leave it alone.
Calling identify(undefined) or identify("") on logout. Ditto.
Calling /v1/identify from a pk_* key without Origin header. Same CORS rules as /v1/track. Add the origin to the allowlist or use sk_*.
Expecting historical events to be rewritten. They aren't. The stitch is always a query-time join. That's fine — ClickHouse joins on (project_id, anonymous_id) are very fast.