Skip to main content
Version: current (0.10)

How Attribution Works

This page explains the model behind Lucia: how the events your site sends become one attributed customer journey per person, across devices and across web2 and web3. If you've done the Quickstart, this is what's happening underneath.

The flow​

Your site + SDKpageView · buttonClicktrackConversionuserInfo · sendWalletInfoLucia APISecure ingestionapi.luciaprotocol.comIdentity resolutionsessions + user+ wallets→ one profileAttribution & insightscampaign creditmulti-touch, scoreddashboard

What the SDK captures​

From the moment it initializes, the SDK records the signals attribution is built from:

  • Pageviews — on load, and on SPA route changes you report.
  • Clicks — automatically (buttons, links) or explicitly via buttonClick.
  • Conversions — the outcomes you care about, with a value, via trackConversion.
  • UTM parameters — read from the landing URL, so paid and campaign traffic is labeled.
  • Identity — userInfo (email / user ID) and sendWalletInfo (on-chain wallets).

Each visit is tracked as a session (per browser tab). Sessions start anonymous — the identity signals below are what connect them to a real person.

How identities resolve into one profile​

This is the core of the product. A visitor usually starts anonymous, and Lucia stitches them into a single customer as identity signals arrive:

  1. Anonymous session — a first visit generates pageview and click events with no known identity, but carries its source (UTM, referrer).
  2. Known user — when you call userInfo (after login or signup), that session — and its history — attaches to a person.
  3. Wallets — sendWalletInfo links each wallet the visitor connects to that same person, so one customer with three wallets isn't counted as three users.
  4. Across devices — because the person (not the browser) is the anchor, a journey that starts on mobile and converts on desktop resolves into one profile.

The result: one profile per real customer, not per session, per device, or per wallet address.

How credit is assigned​

With journeys stitched together, Lucia credits the campaigns that earned each conversion:

  • First-touch (acquisition) — the source that originally brought the user in (also recordable explicitly via trackUserAcquisition).
  • Multi-touch — every touch along the path gets credit, with a score on each match, rather than handing 100% to the last click.
  • Web2 + web3 together — an ad click and an on-chain conversion sit on the same journey, so campaigns are measured on real outcomes, not just sessions.

A worked example​

campaignClick  summer-campaign · x.com     ← first touch (acquisition)
   ↓
pageView       /landing
   ↓
buttonClick    view-pricing
   ↓
addToCart      Pro Plan
   ↓
checkout       /checkout
   ↓
trackConversion  purchase · $240           → credited back to summer-campaign

Each step is a captured event; identity resolution ties them to one customer; attribution credits the summer-campaign · x.com source that started the journey.

Next steps​