Privacy-First Analytics

Install Umami

Follow the Umami installation guide to set up Umami on your server. It can live on the same server as your Inertia Start app or on a separate one.

Add your website to Umami

In your Umami dashboard, add your website. Umami will generate a Website ID that you'll need in the next steps.

Enable analytics in Inertia Start

Turn on the integration with the I_S_ENABLE_ANALYTICS environment variable:

I_S_ENABLE_ANALYTICS=true

Point Inertia Start at your Umami instance

Fill in the details of the Umami instance you set up in step 1:

# The URL where your Umami instance is reachable.
# If Umami runs on the same server with the default port, this is http://localhost:3000.
I_S_UMAMI_HOST=http://localhost:3000

# The name of the tracking script Umami injects into your pages.
# Defaults to "script.js", unless you changed TRACKER_SCRIPT_NAME on your Umami instance.
I_S_UMAMI_TRACKER_SCRIPT=script.js

# The Website ID that Umami generated when you added your website (step 2).
I_S_UMAMI_WEBSITE_ID=

The browser computes a fingerprint

Inertia Start's top-level layouts call the useContext() composable. For guests, it computes a Thumbmark fingerprint and attaches it to Inertia requests in the X-Guest header.

The server resolves the context

The SetContext middleware hashes that fingerprint together with the visitor's IP address, then finds or creates the matching row in the contexts table.

The context ID is remembered in the session and in a first-party context cookie for 90 days, and it's handed to Vue as the contextId Inertia prop. Guest contexts expire after 90 days, and the scheduled expirable:purge command removes them.

To avoid a database write on every request, last_seen_at is refreshed at most once every 5 minutes. Adjust that with I_S_CONTEXT_ACTIVITY_INTERVAL.

The first arrival is attributed

On the request that creates the context, Inertia Start records where the visitor came from:

This is first-touch attribution: all seven columns describe the same arrival, so they are written once and never changed. A visitor who arrives through a Product Hunt link, leaves, and comes back a week later through a Reddit link is still credited to Product Hunt — the channel that actually did the work of finding them.

Because the columns are written together, a source from one arrival can never end up paired with a referrer or a campaign from another. A context created without a landing URL simply stays unattributed; the visitor was already known to you before the campaign link was clicked.

Combined with converted_at, this is what lets you ask which channel produced buyers rather than clicks:

Context::query()
    ->whereNotNull('converted_at')
    ->selectRaw('utm_source, count(*) as customers')
    ->groupBy('utm_source')
    ->orderByDesc('customers')
    ->get();

Money lives in the billing tables rather than on the context, so join them when you want revenue per channel instead of customers per channel:

Context::query()
    ->join('product_purchases', 'product_purchases.user_id', '=', 'contexts.user_id')
    ->selectRaw('contexts.utm_source, count(distinct contexts.id) as customers, sum(product_purchases.amount) as revenue')
    ->groupBy('contexts.utm_source')
    ->orderByDesc('revenue')
    ->get();

product_purchases.amount is stored in the currency's minor unit (cents), so group by currency as well if you sell in more than one.

Registration keeps the history

When the visitor signs up:

• their current context is attached to the new account
• registered_at and registered_via are filled in

The built-in email signup records signup as the registration method, and external auth providers record the provider's driver name (for example google). The column is a plain string, so your own flows can store whatever describes them best.

The first purchase marks the conversion

When a Stripe Checkout session or a Paddle transaction completes successfully — for a configured product or subscription, through either provider — the transaction timestamp is written to the context's converted_at.

Allow the other origins

List every first-party origin in your application's .env:

I_S_CONTEXT_ALLOWED_ORIGINS=https://www.example.com,https://docs.example.com

Origins are matched exactly: scheme and host, plus the port if there is one — no path, no trailing slash. Your application's own origin is always accepted, so you don't need to list it.

Use the same fingerprinting library

Install Thumbmark on the other site:

npm install @thumbmarkjs/thumbmarkjs

Keep the version in sync with the one in your application's package.json. Two different versions can produce two different fingerprints for the same browser, which would split a single visitor into two contexts.

Resolve the context ID

Send the fingerprint to the endpoint in the X-Guest header. No cookie, no CSRF token and no API key are involved.

Include the current URL and the referrer in the body as well. The endpoint only ever sees its own URL, so without them a visitor arriving on your marketing site through a campaign link cannot be attributed:

import { Thumbmark } from '@thumbmarkjs/thumbmarkjs';

export async function resolveContextId(): Promise<string | null> {
  try {
    const { thumbmark } = await new Thumbmark().get();

    const response = await fetch('https://app.example.com/api/context', {
      method: 'POST',
      headers: {
        Accept: 'application/json',
        'Content-Type': 'application/json',
        'X-Guest': thumbmark,
      },
      body: JSON.stringify({
        url: location.href,
        referrer: document.referrer || null,
      }),
    });

    if (!response.ok) {
      return null;
    }

    const { contextId } = (await response.json()) as {
      contextId?: number | string;
    };

    return contextId ? String(contextId) : null;
  } catch {
    return null;
  }
}

Always fail quietly like this. Context tracking is a nice-to-have: a rejected or unreachable request should never keep a page from rendering.

Both fields are optional and each is ignored unless it is a well-formed absolute URL of no more than 2000 characters. They are only used the first time a context is created, so sending them on every page view is harmless.

Point Umami at the same identifier (optional)

If that site also runs the Umami tracker, identify its session with the context you just resolved:

resolveContextId().then((contextId) => {
  if (!contextId) {
    return;
  }

  const identify = () => window.umami?.identify?.(`context:${contextId}`);

  // The tracker script is usually deferred, so it may not be ready yet.
  if (window.umami) {
    identify();
  } else {
    document
      .querySelector('script[data-website-id]')
      ?.addEventListener('load', identify, { once: true });
  }
});

Skip this step if you don't use Umami — cross-site contexts and conversion tracking work perfectly well on their own.