Skip to main content
Version: current (0.10)

Quickstart

Get Lucia capturing events in under 5 minutes. By the end you'll have the SDK installed, initialized with your API key, and your first pageview showing up in the dashboard — the foundation every attribution report is built on.

One SDK, then attribution builds itself

You install a single lightweight SDK and initialize it once. From there, Lucia resolves the events you send into one customer journey per person and credits each conversion to the campaign that earned it — across web2 and web3.

What you'll need​

  • A Lucia account  →  Sign up
  • Your API key from the dashboard (below)
  • A web app you can add a <script> tag or an npm package to

Step 1 — Get your API key​

  1. Log in to your Lucia dashboard.
  2. Open Settings → API Keys.
  3. Copy your key. You'll pass it to the SDK in the next step.
Keep keys in environment variables

Never hard-code your API key in source you commit. Store it in an .env file and read it from import.meta.env / process.env, as shown below.

Step 2 — Install & initialize the SDK​

Pick the path that matches your stack. Both do the same thing: load the SDK and initialize it with your API key.

Add the script to your page <head>. With the data-api-key attribute, the SDK auto-initializes — there's nothing else to call.

<script
  src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"
  data-api-key="YOUR_API_KEY"
></script>

Works with any site or framework, single-page or multi-page. To also capture clicks on every button and link automatically, add data-auto-track-clicks="true".

Framework guide

Using Vite, React, or Next.js? The framework guides pick up from here with copy-paste setup: Vite + TypeScript · React + JavaScript · Next.js.

Step 3 — Track your first event​

Pageviews are the backbone of attribution. If you used the CDN tag, the initial pageview is captured automatically. To record pageviews on client-side route changes — or if you installed via npm — call pageView when the route changes:

import LuciaSDK from 'lucia-sdk';

LuciaSDK.pageView(window.location.pathname);

That's all it takes to start collecting. The next section shows the events that turn raw pageviews into attributed journeys.

Step 4 — Verify it's working ​

  1. Open your app and navigate between a couple of pages.
  2. In the Lucia dashboard, open Insights.

Within a few seconds you should see your pageview events appear.

Don't see anything yet?

The three most common causes are the snippet placed on a page that wasn't reloaded, an ad-blocker on your own browser, or the wrong API key. Turn on debug: true in LuciaSDK.init() to log SDK activity to the console.

That's it — Lucia is live.

Step 5 — Add the events attribution is built from​

With the SDK initialized, a few extra calls let Lucia credit the campaign behind each conversion and resolve a visitor's wallets and sessions into one profile.

Record the outcomes you care about — a purchase, signup, or subscription. This is what campaigns get credited for.

await LuciaSDK.trackConversion('purchase', 49.0, {
  currency: 'USD',
  product: 'Pro Plan',
});

Next steps​