> ## Documentation Index
> Fetch the complete documentation index at: https://lightsage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Measure agent-attributed growth

> Connect visits from recognized AI agent sources to sign-up, demo, checkout, and activation milestones in Agent Analytics.

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.

<Info>
  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.
</Info>

## 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.

<Warning>
  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.
</Warning>

## How the attribution flow works

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Your application identifies the user">
    After authentication, attach your stable application user ID. This connects the known user to the existing anonymous browser journey.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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](/docs/guides/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.

```typescript middleware.ts theme={null}
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.

```tsx app/lightsage-attribution.tsx theme={null}
"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.

<Note>
  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.
</Note>

### Track intent

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

```typescript theme={null}
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:

```html theme={null}
<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.

```typescript theme={null}
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

<Steps>
  <Step title="Open a recognized test source">
    Visit a tracked page with an explicit agent source, for example:

    ```text theme={null}
    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.
  </Step>

  <Step title="Trigger an intent event">
    Use the tracked CTA or call `trackConversion` with `eventStage: "intent"`.
  </Step>

  <Step title="Trigger a completed event">
    Complete the workflow, identify the user, and send the matching `completed` event.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](/docs/guides/agent-tracking-middleware).