Cross-Device Identity Resolution

1. The Cross-Device Problem

The average customer journey spans multiple devices and sessions. Consider this scenario: a user sees a paid search ad on their phone, clicks through and browses for 2 minutes, leaves. Later that day, they search for the brand on their work laptop, read pricing documentation for 10 minutes, and sign up for a webinar using their work email. Two days later, they visit the site on their home desktop, log in, and complete a purchase.

Without identity resolution, analytics reports this as three separate visitors with three separate journeys. The paid search ad gets no attribution. The webinar signup is unconnected to the purchase. The behavioral profile is fragmented across three incomplete records.

Cross-device identity resolution is the process of connecting these fragmented signals into a single, unified customer profile. It is the prerequisite for accurate attribution, complete behavioral profiling, and reliable customer analytics.

2. Identity Graph Data Model

ClickStream models identity as a directed graph where nodes represent identity signals and edges represent observed relationships between signals. This graph-based approach is more flexible than a flat table because it naturally handles many-to-many relationships (one person can have multiple devices, and one device can be shared by multiple people).

2.1 Graph Structure

3. Node Types

4. Edge Types and Confidence

Edges connect two nodes and carry a confidence score (0.0–1.0) representing the system's belief that the two nodes belong to the same person.

Each signal type carries a confidence weight in the shipped graph (hashed email 0.30, hashed phone / customer ID 0.20, social-login OAuth subjects 0.25, raw email/phone 0.15, mobile ad ID 0.10, device fingerprint 0.08, visitor ID 0.05). Probabilistic edges expire on TTLs from 7 to 90 days; deterministic signals never expire. Probabilistic cross-device merges require a combined confidence of at least 0.60 and a person-distinguishing signal.

Every resolved person also carries a confidence band — deterministic, probabilistic, or observed — so downstream consumers always know how an identity was established.

5. Deterministic Matching

Deterministic matching creates high-confidence edges based on explicit identity signals. These edges are created when the visitor takes an action that directly reveals their identity:

• Login event: The visitor authenticates with an email/password. This creates a deterministic login edge between the current cookie and the email hash.
• Form submission: The visitor enters their email in a form (newsletter, demo request, contact form). Edge type: form_submit.
• Checkout: The visitor provides email during purchase. Edge type: checkout.
• OAuth login: The visitor signs in via Google, Apple, Facebook, or LinkedIn. ClickStream stores the OAuth subject as a per-tenant HMAC'd deterministic cross-device key — an authenticated identity anchor that never leaves the tenant's keyspace.

Deterministic edges are the strongest signals in the identity graph. A single deterministic edge can resolve a previously anonymous visitor into a known customer and link all their historical behavioral data to that customer profile.

6. Probabilistic Matching

Probabilistic matching creates lower-confidence edges based on statistical signals that suggest two nodes may belong to the same person:

6.1 IP Clustering

When two cookies are observed from the same hashed IP, they may belong to the same person using different browsers or devices. The shipped graph clusters households by hashed IP (raw IPs are never stored), excludes hosting, VPN, proxy, and Tor networks from clustering, and evaluates probabilistic cross-device candidates over a 30-day window. IP evidence alone is weighted low because addresses are shared across households and offices.

6.2 Signature Matching

When two cookies share the same device signature (screen resolution, timezone, language, platform, GPU renderer), they may be the same device with cleared cookies. Device fingerprints carry a deliberately low signal weight (0.08) in the shipped graph because signatures are not perfectly unique — a fingerprint match alone never triggers a merge.

6.3 Behavioral Similarity

When two cookies exhibit similar behavioral patterns (same content affinity, similar navigation paths, similar engagement scores) from the same geographic region, they may be the same person. Behavioral-profile similarity is used only as supporting evidence for probabilistic matching — never as a merge trigger on its own.

6.4 Confidence Boosting

Probabilistic confidence increases when multiple independent signals corroborate each other. The corroboration model below is illustrative — a simplification, not the shipped formula; in production, probabilistic merges are gated on a combined confidence of at least 0.60 plus a person-distinguishing signal:

7. Graph Resolution Algorithm

The graph resolution algorithm merges nodes that are connected by edges exceeding a confidence threshold. The algorithm runs incrementally on every new edge creation:

7.1 Algorithm Steps

1. New edge arrives: A new identity signal creates an edge (e.g., a login event creates a cookie-to-email edge).
2. Transitive closure: Find all nodes reachable from either endpoint of the new edge through edges with confidence ≥ 0.60 (subject to merge-eligibility guardrails).
3. Cluster identification: Group all reachable nodes into a single identity cluster.
4. Primary identity selection: Select the highest-fidelity node as the cluster's primary identifier (preference order: email hash > phone hash > external ID > oldest cookie).
5. Profile merge: Aggregate behavioral scores, session histories, and attribution data across all nodes in the cluster.

7.2 Conflict Resolution

When the algorithm detects that two previously separate identity clusters may belong to the same person (e.g., a visitor logs in on their phone and the email hash connects their phone cookie to their desktop cookie), it evaluates a cluster merge. Merges are never unconditional: the shipped system blocks merges on conflicting deterministic identifiers, never auto-merges an email seen on more than 5 visitors (the shared-mailbox cap), requires corroboration for mobile-ad-ID links, and records every merge in an auditable merge history — ClickStream deliberately refuses merges other tools would make. A merge that passes those guardrails executes conceptually like this:

8. D1 Database Schema

The identity graph is stored in Cloudflare D1, a SQLite database at the edge. The production schema (22 migrations) centers on identity nodes with on-row deterministic identifiers, weighted edges, append-only person signals, materialized person profiles, a merge history log, and per-person confidence bands. A simplified conceptual model:

8.1 identity_nodes

8.2 identity_edges

8.3 identity_clusters

9. Identity Resolution Flow

The identity resolution flow ingests signals from every incoming event at the edge; graph processing runs asynchronously through a queue consumer:

1. Cookie received: Edge worker reads the first-party cookie. If no cookie exists, a new one is created.
2. Node lookup: The worker queries D1 for an existing node matching this cookie ID.
3. New visitor path: If no node exists, create a new node, a new single-node cluster, and assign the cluster ID.
4. Returning visitor path: If the node exists, update last_seen and proceed to edge evaluation.
5. Edge evaluation: Check if the event contains any identity signals (email in form data, login event, etc.). If yes, create deterministic edges.
6. Probabilistic evaluation: Compare device signature, IP, and behavioral signals against recent nodes. Create probabilistic edges where applicable.
7. Graph resolution: If new edges connect previously separate clusters, execute cluster merge.
8. Profile update: Update the cluster's aggregate behavioral scores, session count, and last-seen timestamp.

One guardrail worth noting: bot-classified visitors are quarantined out of the identity graph entirely — bots never become people.

10. Cross-Site Identity (Multi-Domain)

Some customers operate multiple domains (e.g., marketing-site.com and app.product.com). ClickStream supports cross-site identity resolution while maintaining data isolation:

10.1 Shared Email Hash

When a visitor logs in on one domain and the same email hash appears on another domain (both belonging to the same customer), the identity graph creates a cross-site edge. This requires both domains to be configured under the same ClickStream account.

10.2 Cross-Site Edge Confidence

Relative strength of cross-site signals (illustrative — not shipped confidence values):

11. Conclusion

Cross-device identity resolution transforms fragmented analytics into unified customer intelligence. ClickStream's graph-based identity model — with typed nodes, weighted edges, confidence scoring, and incremental resolution — handles the complexity of real-world customer journeys where one person uses multiple devices, clears cookies, switches browsers, and interacts across multiple company domains.

The key architectural decisions that make this work are: first-party cookies as the primary anchor (high persistence, high confidence), deterministic matching via email hash as the cross-device bridge, probabilistic matching as a supplementary signal with conservative confidence thresholds, and incremental graph resolution that executes on every event without batch processing.

The D1 schema is designed for edge-first execution: simple, denormalized where needed for performance, and partitioned by site for data isolation. The identity graph is not a data warehouse feature that runs nightly. It is a continuously updating system that ingests identity signals from every page view, form submission, and login event at the edge — no nightly batch required.