attributed growth.md

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.

[!NOTE]

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:

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.

How the attribution flow works

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

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

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

4. Your application identifies the user

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

5. 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:

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.

[!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.

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:

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

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

2. Trigger an intent event

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

3. Trigger a completed event

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

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