Docs

Integration Guides

Buyer Trace

Track AI-referred buyers from click to conversion. One script tag enables buyer attribution, intent tracking, and conversion analytics.

Buyer Trace

Inception Trace automatically tracks when buyers arrive at your site from AI agent referrals (ChatGPT, Claude, Gemini, Perplexity, Copilot, Grok, and others). It attributes each visit to the originating AI platform and intent context, then measures conversion and revenue. The edge worker handles arrival detection automatically; the JS snippet adds client-side confirmation and conversion tracking.

How It Works

AI Agent Response → URLs contain intent context identifiers
                      e.g., ?ia=compare-athletic-cushion

Buyer Clicks URL  → Edge Worker (Track 1)
                      Detects ?ia= param or /__ia/ path
                      Sets _ia_trace cookie
                      Records buyer arrival

Browser Loads     → JS Snippet (Track 2)
                      Confirms trace context
                      Fires onBuyerTrace callback
                      Enables conversion tracking

Buyer Converts    → __ia_markConversion()
                      Attributes revenue to AI platform
                      Links to original agent session

Track 1 (edge worker) detects arrivals server-side from URL parameters (?ia=) or path segments (/__ia/). Track 2 (JS snippet) provides client-side confirmation and enables conversion tracking. Both tracks deduplicate automatically via browser session ID.

Session correlation links each buyer arrival back to the original AI agent interaction, enabling end-to-end attribution from agent query to purchase.

Installation

Add the snippet to your site’s <head> on all pages:

<script
  src="https://cdn.inceptionagents.com/beacon.js"
  data-api-key="YOUR_API_KEY"
  data-conversion-tracking
  defer
></script>

npm / ES Module

npm install @inception-agents/browser

import { init } from '@inception-agents/browser';

init({
  apiKey: 'YOUR_API_KEY',
  enableConversionTracking: true,
});

The snippet is lightweight (~5KB) and SSR-safe. It will not execute on the server if window is unavailable.

Conversion Tracking

Once the snippet is installed with data-conversion-tracking (or enableConversionTracking: true), call __ia_markConversion() when a buyer completes a conversion:

// On purchase completion (e.g., thank-you page)
window.__ia_markConversion('purchase', 99.99);

// On signup (no revenue)
window.__ia_markConversion('signup');

// Custom event
window.__ia_markConversion('demo_request');

Behavior:

  • The first argument is the conversion event name (defaults to 'purchase' if omitted)
  • The second argument is the revenue amount (optional, must be a finite number)
  • The function is idempotent per session — calling it multiple times in the same browser session will only record the first conversion and log a warning in debug mode
  • Revenue is validated: non-numeric, NaN, and Infinity values are silently ignored

Where to Place the Conversion Call

Add the conversion call on your confirmation or thank-you page:

<!-- Order confirmation page -->
<script>
  // Assumes order total is available on the page
  if (window.__ia_markConversion) {
    window.__ia_markConversion('purchase', ORDER_TOTAL);
  }
</script>

For single-page apps, call it after the conversion event completes (e.g., after a successful API response).

Configuration Options

Script Tag Attributes

AttributeDescriptionDefault
data-api-keyYour Inception Agents API key (required)—
data-tenant-idYour tenant IDAuto-detected
data-api-urlCustom API endpointProduction API
data-conversion-trackingEnable window.__ia_markConversion()Disabled
data-debugLog trace events to browser consoleDisabled

Programmatic Configuration

When using the npm package, pass a config object to init():

import { init } from '@inception-agents/browser';

init({
  apiKey: 'YOUR_API_KEY',          // Required
  tenantId: 'YOUR_TENANT_ID',     // Optional, auto-detected
  apiUrl: 'https://custom.api',   // Optional
  enableConversionTracking: true,  // Optional
  debug: true,                     // Optional

  // Callback fired when a buyer trace context is detected
  onBuyerTrace: (trace) => {
    console.log('AI buyer detected:', trace);
    // trace.intentContextId — e.g., 'compare-athletic-cushion'
    // trace.source — 'url_param' | 'url_path' | 'cookie' | 'referrer'
    // trace.aiProvider — 'chatgpt' | 'claude' | 'gemini' | etc.
  },
});

The onBuyerTrace Callback

The onBuyerTrace callback fires whenever a buyer trace context is detected — whether from a URL parameter, path segment, cookie, or AI referrer. Use it to forward events to your existing analytics stack.

Google Analytics 4 (GA4)

init({
  apiKey: 'YOUR_API_KEY',
  enableConversionTracking: true,
  onBuyerTrace: (trace) => {
    gtag('event', 'ai_buyer_arrival', {
      ai_provider: trace.aiProvider,
      intent_context: trace.intentContextId,
      detection_source: trace.source,
    });
  },
});

Segment

onBuyerTrace: (trace) => {
  analytics.track('AI Buyer Arrival', {
    aiProvider: trace.aiProvider,
    intentContextId: trace.intentContextId,
    source: trace.source,
  });
}

Custom Data Layer

onBuyerTrace: (trace) => {
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    event: 'ai_buyer_arrival',
    ai_provider: trace.aiProvider,
    intent_context: trace.intentContextId,
  });
}

How Trace Detection Works

The snippet checks for trace context in this order:

  1. URL Parameter (?ia=compare-athletic) — The most common method. The edge worker appends this parameter to URLs served to AI agents. When a buyer clicks the link, the snippet reads the ia parameter.

  2. URL Path Segment (/__ia/compare-athletic) — Used specifically by Claude, which tends to preserve path segments more reliably than query parameters. The edge worker strips the /__ia/ segment before forwarding to your origin server, so your application never sees it.

  3. Trace Cookie (_ia_trace) — Set by the edge worker on first arrival. Maintains trace context as the buyer navigates across pages within the same session.

  4. AI Referrer Detection — Fallback when no URL identifier is present. The snippet checks document.referrer against known AI platform domains. This provides platform attribution without intent context.

Supported AI Platforms

PlatformDetection MethodIntent Context
ChatGPTReferrer + URL param (?ia=)Yes
ClaudeReferrer + URL path (/__ia/)Yes
GeminiReferrer + URL param (?ia=)Yes
PerplexityReferrer onlyNo (referrer fallback)
CopilotReferrer + URL param (?ia=)Yes
GrokReferrer + URL param (?ia=)Yes
You.comReferrerReferrer fallback
PhindReferrerReferrer fallback
KagiReferrerReferrer fallback

Platforms with “Yes” intent context provide full buyer attribution including the semantic intent (e.g., “compare athletic shoes”). Referrer-only platforms provide platform attribution but without specific intent context.

Verification

Quick Test

  1. Add data-debug to your script tag
  2. Open any page on your site with ?ia=test-context appended to the URL
  3. Open the browser console — you should see: 
    [inception-agents] trace context: {intentContextId: "test-context", source: "url_param", aiProvider: null}
  4. Call window.__ia_markConversion('test') in the console — you should see: 
    [inception-agents] conversion tracked: {event: "test", revenue: undefined}

Production Verification

After enabling Inception Trace, check your dashboard Analytics tab for:

  • Buyer Arrivals — each arrival shows the intent context, AI platform, and landing page
  • Session Correlation — arrivals linked to their originating agent interactions
  • Conversion Rate — percentage of AI-referred buyers who convert

Privacy

  • No PII collected. The snippet tracks intent context identifiers (e.g., “compare-athletic-cushion”), not personal data.
  • IP addresses are hashed. Client IPs are HMAC-SHA256 hashed at the edge before storage. Raw IPs are never stored.
  • First-party cookie only. The _ia_trace cookie is HttpOnly, Secure, SameSite=Lax, with a 30-day TTL. It contains only the intent context identifier and AI platform name.
  • No cross-site tracking. Each merchant’s data is isolated via row-level security. There is no cross-store identity stitching.

Limitations

  • Full page loads only (v1). SPA navigation within the same page is not tracked unless the URL changes with a full page load. Support for SPA route changes is planned.
  • Conversion is session-scoped. __ia_markConversion() records one conversion per browser session. Multi-conversion tracking within a single session is not supported in v1.
  • Client-reported revenue. Revenue attribution is based on the value passed to __ia_markConversion(). This is directional (same trust model as Google Analytics), not financial-grade.