npm package: @superlines/pixel
Description: Lightweight AI search analytics pixel for tracking LLM bot traffic and human visitors
Author: Superlines
Latest version: 1.0.0

# @superlines/pixel

Lightweight analytics pixel for tracking AI bot traffic and human visitors. Detect when ChatGPT, Claude, Perplexity, and other LLMs visit your website.

[![npm version](https://badge.fury.io/js/%40superlines%2Fpixel.svg)](https://www.npmjs.com/package/@superlines/pixel)
[![gzip size](https://img.shields.io/bundlephobia/minzip/@superlines/pixel)](https://bundlephobia.com/package/@superlines/pixel)

## Features

- 🪶 **Ultra-lightweight** - Under 2KB gzipped
- ⚡ **Zero dependencies** - Pure vanilla JavaScript
- 🤖 **AI bot detection** - Track ChatGPT, Claude, Perplexity, Gemini, and more
- 📱 **SPA support** - Automatic navigation tracking for React, Vue, Next.js
- 🔒 **Privacy-friendly** - Respects Do Not Track, no cookies
- 🌐 **CDN-ready** - Works with jsDelivr, unpkg, or self-hosted

## Quick Start

### Option 1: CDN (Recommended)

Add this script tag to your HTML:

```html
<script 
  src="https://cdn.jsdelivr.net/npm/@superlines/pixel/dist/superlines.min.js" 
  data-tid="YOUR_TRACKING_ID"
  async
></script>
```

That's it! The script automatically tracks page views.

### Option 2: npm

```bash
npm install @superlines/pixel
```

```javascript
import { Superlines } from '@superlines/pixel'

Superlines.init({ trackingId: 'YOUR_TRACKING_ID' })
```

## CDN Options

### jsDelivr (Recommended)

```html
<!-- Latest version -->
<script src="https://cdn.jsdelivr.net/npm/@superlines/pixel/dist/superlines.min.js" data-tid="YOUR_TRACKING_ID" async></script>

<!-- Specific version (recommended for production) -->
<script src="https://cdn.jsdelivr.net/npm/@superlines/pixel@1.0.0/dist/superlines.min.js" data-tid="YOUR_TRACKING_ID" async></script>
```

### unpkg

```html
<script src="https://unpkg.com/@superlines/pixel/dist/superlines.min.js" data-tid="YOUR_TRACKING_ID" async></script>
```

### Self-hosted

Download `superlines.min.js` from [releases](https://github.com/Superlines/aisearchindex-pixel/releases) and host on your own CDN.

## Configuration

### Script Attributes

| Attribute | Required | Default | Description |
|-----------|----------|---------|-------------|
| `data-tid` | ✅ | - | Your Superlines tracking ID |
| `data-endpoint` | ❌ | Superlines API | Custom endpoint URL |
| `data-spa` | ❌ | `false` | Enable SPA navigation tracking |
| `data-debug` | ❌ | `false` | Enable console debug logs |
| `data-dnt` | ❌ | `false` | Respect Do Not Track setting |

### Example with Options

```html
<script 
  src="https://cdn.jsdelivr.net/npm/@superlines/pixel/dist/superlines.min.js" 
  data-tid="YOUR_TRACKING_ID"
  data-spa="true"
  data-debug="true"
  async
></script>
```

## Programmatic Usage

For advanced use cases, use the full library:

```javascript
import { Superlines } from '@superlines/pixel'

// Initialize with options
Superlines.init({
  trackingId: 'YOUR_TRACKING_ID',
  trackSpa: true,           // Auto-track SPA navigation
  autoTrack: true,          // Auto-track initial page view
  respectDnt: false,        // Respect Do Not Track header
  debug: false,             // Enable debug logging
  customData: {             // Custom data sent with every event
    plan: 'pro',
    version: '2.1.0'
  }
})

// Manual tracking
Superlines.track()

// Track with custom data
Superlines.track({
  event: 'signup',
  data: { method: 'google' }
})

// Track a specific URL
Superlines.track({
  url: 'https://example.com/thank-you',
  referrer: 'https://example.com/checkout'
})
```

## Framework Examples

### Next.js (App Router)

```tsx
// app/layout.tsx
import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script 
          src="https://cdn.jsdelivr.net/npm/@superlines/pixel/dist/superlines.min.js"
          data-tid="YOUR_TRACKING_ID"
          data-spa="true"
          strategy="afterInteractive"
        />
      </body>
    </html>
  )
}
```

### React (Vite / CRA)

```tsx
// index.html or public/index.html
<script 
  src="https://cdn.jsdelivr.net/npm/@superlines/pixel/dist/superlines.min.js" 
  data-tid="YOUR_TRACKING_ID"
  data-spa="true"
  async
></script>
```

### Vue

```html
<!-- index.html -->
<script 
  src="https://cdn.jsdelivr.net/npm/@superlines/pixel/dist/superlines.min.js" 
  data-tid="YOUR_TRACKING_ID"
  data-spa="true"
  async
></script>
```

### Astro

```astro
---
// Layout.astro
---
<html>
  <head>
    <script 
      src="https://cdn.jsdelivr.net/npm/@superlines/pixel/dist/superlines.min.js" 
      data-tid="YOUR_TRACKING_ID"
      is:inline
    ></script>
  </head>
</html>
```

### WordPress

Add to your theme's `header.php` or use a plugin like "Insert Headers and Footers":

```html
<script 
  src="https://cdn.jsdelivr.net/npm/@superlines/pixel/dist/superlines.min.js" 
  data-tid="YOUR_TRACKING_ID"
  async
></script>
```

### Webflow

1. Go to **Project Settings** → **Custom Code**
2. Paste the script in **Head Code** or **Footer Code**

### Shopify

1. Go to **Online Store** → **Themes** → **Edit code**
2. Open `theme.liquid`
3. Add the script before `</head>`

### Google Tag Manager

1. Create a new **Custom HTML** tag
2. Paste the script
3. Trigger on **All Pages**

## What Gets Tracked

Each page view includes:
- Page URL and referrer
- Timestamp and session ID
- Screen and viewport dimensions
- Connection type (if available)
- Custom data (if configured)

The server-side pixel detects:
- **AI Bots**: ChatGPT, Claude, Perplexity, GPTBot, Google-Extended, etc.
- **Search Engines**: Googlebot, Bingbot, DuckDuckBot, etc.
- **Social Previews**: Facebook, Twitter, LinkedIn, etc.
- **Human visitors**: Real users browsing your site

## Privacy

- **No cookies** - Uses sessionStorage for deduplication only
- **No PII** - Never collects personal information
- **DNT support** - Optional respect for Do Not Track
- **Minimal data** - Only collects what's needed for analytics

## Browser Support

- Chrome, Firefox, Safari, Edge (last 2 versions)
- IE11 not supported (uses modern APIs)

## Self-Hosting

If you prefer to self-host:

1. Download the latest release
2. Host `superlines.min.js` on your CDN
3. Update `data-endpoint` to point to your Superlines instance

```html
<script 
  src="https://your-cdn.com/superlines.min.js" 
  data-tid="YOUR_TRACKING_ID"
  data-endpoint="https://your-app.com/api/pixel"
  async
></script>
```

## Development

```bash
# Install dependencies
npm install

# Build all formats
npm run build

# Watch mode
npm run dev

# Check bundle sizes
npm run size
```

## License

MIT © [Superlines](https://superlines.io)

---

Built with ❤️ by [Superlines](https://superlines.io) - AI Search Analytics