npm package: @inception-agents/browser
Description: Lightweight client-side beacon (&lt;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.
Latest version: 0.1.0

# @inception-agents/browser

Lightweight client-side beacon (&lt;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)

```html
<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

```bash
npm install @inception-agents/browser
```

```typescript
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.

```typescript
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](https://www.inceptionagents.com/docs/integrations/browser)
- [@inception-agents/core](https://www.npmjs.com/package/@inception-agents/core)