Measure agent-attributed growth

Agent-attributed growth connects a browser visit from a recognized AI source to conversion milestones that happen on your website or app. Use it to measure outcomes such as sign-up intent, completed registration, demo requests, checkout, and API key creation.

Agent Attributed Conversions is enabled per organization. If you do not see this panel under Agent Analytics, ask Lightsage to enable attribution for your organization.

What agent-attributed means

Lightsage attributes a conversion when the visitor’s browser carries a recognized AI agent source and your application sends an explicit conversion event. The source can come from:

An external referrer such as chatgpt.com, claude.ai, or perplexity.ai
A source parameter such as utm_source=chatgpt.com
A stored first-touch or session touch captured earlier in the same browser

Lightsage normalizes known aliases and domains to agent names. For example, chat.openai.com, chatgpt.com, and openai resolve to ChatGPT. Plain GitHub referrals are excluded, while github-copilot remains a valid agent source.

An agent crawler request does not automatically become a human conversion. The human browser must retain an agent source through its referrer, URL parameters, or stored attribution state. Treat this as acquisition attribution, not proof that a specific crawler request caused the outcome.

How the attribution flow works

A visitor arrives from an AI source

The browser helper resolves the current source from explicit URL parameters first, then from an external referrer. Internal referrals across your own subdomains are ignored.

Lightsage creates browser identity

Lightsage stores a first-party visitor ID and a rolling session ID. By default, the visitor ID lasts 365 days and the session lasts 30 minutes.

Your application records milestones

Send an intent event for a meaningful action such as starting sign-up. Send a completed event only after the outcome is confirmed.

Your application identifies the user

After authentication, attach your stable application user ID. This connects the known user to the existing anonymous browser journey.

Agent Analytics builds the funnel

Lightsage keeps conversions from recognized agent sources, deduplicates events by event ID, groups events by browser or user identity, and orders funnel steps from observed journeys. You can override the displayed order in the dashboard.

Lightsage stores three attribution touchpoints:

Touchpoint	Meaning
First touch	The first valid acquisition source for the visitor. A later agent source can replace an initial `direct` touch.
Session touch	The source that began the current browser session.
Current touch	The source resolved from the current page URL and referrer.

Before you begin

You need:

An Agent Analytics site configured with the agent tracking middleware or another supported request-tracking integration
@lightsage/agent-tracker installed on the pages where conversions happen
A stable event naming scheme for your funnel
An opaque application user ID if you want known-user lookup

If visits begin on www.example.com and conversions happen on app.example.com, configure the apex domain in both the middleware and browser helper. This keeps visitor, session, and attribution cookies available across subdomains.

middleware.ts

import { withAgentTracking } from "@lightsage/agent-tracker/next";

export default withAgentTracking({
  apiKey: process.env.LIGHTSAGE_API_KEY!,
  siteDomain: "example.com",
});

Set up browser attribution

Initialize the browser helper

Mount the browser helper once near the root of your client application.

app/lightsage-attribution.tsx

"use client";

import { useEffect } from "react";
import { initLightsagePixel } from "@lightsage/agent-tracker/browser";

export const lightsageOptions = {
  apiKey: process.env.NEXT_PUBLIC_LIGHTSAGE_API_KEY!,
  siteDomain: "example.com",
  cookieDomain: ".example.com",
};

export function LightsageAttribution() {
  useEffect(() => {
    void initLightsagePixel(lightsageOptions);
  }, []);

  return null;
}

Omit siteDomain and cookieDomain when all tracked pages use one hostname. Do not commit the tracking key directly in source control.

If your security policy requires the tracking key to remain server-side, set conversionEndpoint to a same-origin proxy and add the key in that server route.

Track intent

Use intent for an action that shows conversion interest but does not confirm the outcome.

import { trackConversion } from "@lightsage/agent-tracker/browser";
import { lightsageOptions } from "./lightsage-attribution";

await trackConversion(
  "signup.intent",
  { placement: "pricing" },
  {
    ...lightsageOptions,
    label: "Start sign up",
    eventStage: "intent",
  },
);

For simple CTA clicks, initLightsagePixel also supports declarative capture:

<button
  data-lightsage-conversion="signup.intent"
  data-lightsage-conversion-stage="intent"
  data-lightsage-label="Start sign up"
>
  Start free trial
</button>

Identify the user and track completion

Call identifyUser after authentication succeeds, then record the confirmed outcome.

import {
  identifyUser,
  trackConversion,
} from "@lightsage/agent-tracker/browser";
import { lightsageOptions } from "./lightsage-attribution";

async function onSignupComplete(user: { id: string; plan: string }) {
  await identifyUser(user.id, lightsageOptions);

  await trackConversion(
    "signup.completed",
    { plan: user.plan },
    {
      ...lightsageOptions,
      label: "Complete sign up",
      eventStage: "completed",
    },
  );
}

Use an opaque, stable user ID. Do not use an email address or other personal data as the identifier.

Design your conversion events

Track a small set of meaningful milestones instead of every click.

Event name	Label	Stage
`signup.intent`	Start sign up	`intent`
`signup.completed`	Complete sign up	`completed`
`demo.requested`	Request a demo	`completed`
`checkout.completed`	Complete checkout	`completed`
`api_key.created`	Create API key	`completed`

Keep the event name stable because Lightsage uses it as the aggregation key. Use the label for the human-readable name shown in the dashboard. Each conversion has an automatically generated event ID. Lightsage deduplicates repeated submissions of the same event ID for the same tracked site. Custom properties must be valid JSON and no larger than 8 KB.

Read the dashboard

The Agent Attributed Conversions panel applies the selected Agent Analytics time range.

Metric	Calculation
Intent	Unique identities that recorded at least one `intent` event.
Completed	Unique identities that recorded a `completed` event after an `intent` event in the selected range.
Conversion rate	Completed identities divided by intent identities.
Drop-off	Intent identities minus completed identities.

Identity resolution uses the browser visitor ID first, then your external user ID, then the session ID. A completed event without an earlier intent event still appears in the event breakdown, but it does not increase the overall Completed metric or conversion rate. The conversion event chart uses unique identities for each event type. Lightsage infers the default order from observed journeys. Click Edit order to pin important events into a specific sequence; events you do not pin continue to use the inferred order. Use the activity views to inspect the underlying data:

Visitors groups conversion milestones by identity and shows known user IDs when available.
Live logs refreshes recent agent-attributed activity every five seconds.
Search user ID finds events with an exact external user ID match.
Export downloads conversion and available journey rows as CSV.

The browser helper initializes identity and conversion capture. It does not replace the request tracker that powers the main Agent Analytics visit, page, status, and latency reports. Browser page steps appear in conversion journeys only when your integration sends client-navigation events.

Validate your setup

Open a recognized test source

Visit a tracked page with an explicit agent source, for example:

https://www.example.com/pricing?utm_source=chatgpt.com&utm_medium=organic_ai

Do not use an arbitrary value such as utm_source=test; conversions from unrecognized sources are not included in this panel.

Trigger an intent event

Use the tracked CTA or call trackConversion with eventStage: "intent".

Trigger a completed event

Complete the workflow, identify the user, and send the matching completed event.

Confirm the result

Open Agent Analytics, select the relevant site and time range, and check Agent Attributed Conversions. The event should show the normalized agent source, visitor ID, and user ID when supplied.

Attribution limitations

Cookies and storage restrictions can prevent identity from persisting.
Anonymous journeys do not merge across browsers or devices automatically.
Identifying a user improves known-user lookup but does not recreate events that occurred before Lightsage tracking was installed.
Direct, search, social, and other non-agent conversions are intentionally excluded from this panel.
Referrer data can be missing when an agent or browser removes it. Use explicit source parameters when you control the link.

For agent visit detection and hosting-specific installation options, see Detect AI agent visits with agent tracking middleware.

Quickstart

Workflows

Agent Analytics

Integrations

Lightsage Docs Agent

Measure agent-attributed growth

What agent-attributed means

How the attribution flow works

Before you begin

Set up browser attribution

Initialize the browser helper

Track intent

Identify the user and track completion

Design your conversion events

Read the dashboard

Validate your setup

Attribution limitations

​What agent-attributed means

​How the attribution flow works

​Before you begin

​Set up browser attribution

​Initialize the browser helper

​Track intent

​Identify the user and track completion

​Design your conversion events

​Read the dashboard

​Validate your setup

​Attribution limitations

What agent-attributed means

How the attribution flow works

Before you begin

Set up browser attribution

Initialize the browser helper

Track intent

Identify the user and track completion

Design your conversion events

Read the dashboard

Validate your setup

Attribution limitations