@inception-agents/browser

Lightweight client-side beacon (<5 KB) for tracking AI agent referral attribution. Detects when users arrive from AI platforms (ChatGPT, Perplexity, Claude, Gemini, Copilot, and more) and fires attribution events to the Inception Agents analytics API.

Installation

Script Tag (recommended for most sites)

<script
  src="https://cdn.inceptionagents.com/beacon.js"
  data-api-key="iak_your_api_key"
  data-tenant-id="t_your_tenant_id"
></script>

The script auto-initializes from data-* attributes. No additional JavaScript required.

npm

npm install @inception-agents/browser

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

init({
  apiKey: 'iak_your_api_key',
  tenantId: 't_your_tenant_id',
});

API Reference

init(config)

Initialize the browser beacon. Automatically detects AI referrals from document.referrer and UTM parameters, then fires an attribution event if an AI source is detected.

init({
  apiKey: 'iak_your_api_key',
  tenantId: 't_your_tenant_id',
  debug: true, // Log events to console
});

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your Inception Agents API key | | tenantId | string | — | Your tenant ID | | apiUrl | string | https://inception-agents-api... | API base URL | | debug | boolean | false | Log referral events to the browser console |

Script Tag Attributes

| Attribute | Description | |-----------|-------------| | data-api-key | Your Inception Agents API key (required) | | data-tenant-id | Your tenant ID | | data-api-url | Custom API base URL | | data-debug | Enable debug logging (presence enables) |

Detected AI Platforms

The beacon detects referrals from these AI platforms via document.referrer:

• ChatGPT — chat.openai.com, chatgpt.com
• Perplexity — perplexity.ai
• Claude — claude.ai
• Gemini — gemini.google.com
• Copilot — copilot.microsoft.com
• You.com — you.com
• Phind — phind.com
• Kagi — kagi.com

Additionally, UTM parameters are checked for AI-attributed sources: utm_source=chatgpt, utm_source=perplexity, utm_source=claude, utm_source=gemini, utm_source=copilot, utm_source=ai-agent.

How It Works

1. On page load, the beacon checks document.referrer against known AI platform domains
2. It also checks URL parameters for AI-attributed utm_source values
3. If an AI referral is detected, an attribution event is sent to the Inception Agents API
4. Events are sent via navigator.sendBeacon() (with fetch fallback) for reliability
5. A session ID is persisted in sessionStorage to group events within a session
6. Only AI referrals fire events to minimize noise

Builds

The package ships two build formats:

• ESM (dist/index.mjs) — For npm/bundler usage with import
• IIFE (dist/index.global.js) — For script tag usage, exposes window.InceptionAgents

Exported Types

• BeaconConfig — Configuration for init()
• ReferralEvent — Shape of the attribution event sent to the API

Related

• Full documentation
• @inception-agents/core