Integration

Identity Stitching

Lehnz tracks events under a single user_id per shopper. While anonymous, assign a stable random ID and use it on every event. At sign-in, reconcile the two identities with one identify event. Any deviation silently drops attribution.

The four-step contract

On first visit, mint an anonymous user ID

Generate a UUID v4, persist it to localStorage, and use it as user_id on every event while the shopper is anonymous.

identity.js

let userId = localStorage.getItem('lehnz_user_id');
if (!userId) {
  userId = crypto.randomUUID();
  localStorage.setItem('lehnz_user_id', userId);
}

Lehnz never mints this ID for you. Owning it client-side guarantees stability across page loads, tabs, and reconnects.

On login or signup, send exactly one identify event

The moment authentication completes, fire one event linking the anonymous ID to the real one.

curl -X POST https://api.lehnz.com/v1/ingest/events/ingest \
  -H "X-API-KEY: lehnz_pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_family": "system",
    "event_name": "identify",
    "user_id": "<real_user_id>",
    "previous_user_id": "<anon_uuid>"
  }'

event_family: "system" and previous_user_id are both required for identify events.

Then update localStorage and continue tracking under the real ID:

onSignIn.js

localStorage.setItem('lehnz_user_id', realUserId);

On logout, mint a fresh anonymous ID

onSignOut.js

const newAnon = crypto.randomUUID();
localStorage.setItem('lehnz_user_id', newAnon);

The new session is unrelated to the previous user. Reusing the old anonymous ID would commingle two sessions.

On account merge (rare), send identify with the deprecated real ID

If the same person signs in with a second account that you then merge into a primary, send another identify event:

curl -X POST https://api.lehnz.com/v1/ingest/events/ingest \
  -H "X-API-KEY: lehnz_pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_family": "system",
    "event_name": "identify",
    "user_id": "<primary_user_id>",
    "previous_user_id": "<deprecated_user_id>"
  }'

What happens server-side

When an identify event lands, lehnz-backend writes a Redis hash entry: alias:{tenantId} {previous_user_id} -> {user_id}. The downstream consumer resolves aliases at read time in O(1). Past events are never rewritten; the alias map is the join table.

If multiple identify events form a chain (anon_a -> real_x, then real_x -> real_y), resolution walks the chain.

Common mistakes

Don't fire identify repeatedly on every page after login

Once is enough. The alias is durable.

Don't omit event_family: "system" on identify events

They will return 400 Bad Request.

Don't reuse a real user_id as the next anonymous ID after logout

Generate a fresh UUID.