@aisearchindex/pixel

v1.1.0

Published

3 months ago

Lightweight AI search analytics pixel for tracking LLM bot traffic and human visitors

0High
0Medium
0Low

ihmissuti

analytics tracking pixel ai llm bot chatgpt claude perplexity seo web-analytics ai-search aisearchindex

@aisearchindex/pixel

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

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:

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

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

Option 2: npm

npm install @aisearchindex/pixel

import { AISearchIndex } from '@aisearchindex/pixel'

AISearchIndex.init({ trackingId: 'YOUR_TRACKING_ID' })

CDN Options

jsDelivr (Recommended)

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

<!-- Specific version (recommended for production) -->
<script src="https://cdn.jsdelivr.net/npm/@aisearchindex/[email protected]/dist/aisearchindex.min.js" data-tid="YOUR_TRACKING_ID" async></script>

unpkg

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

Self-hosted

Download aisearchindex.min.js from releases and host on your own CDN.

Configuration

Script Attributes

| Attribute | Required | Default | Description | |-----------|----------|---------|-------------| | data-tid | Yes | - | Your AI Search Index tracking ID | | data-endpoint | No | AI Search Index API | Custom endpoint URL | | data-spa | No | false | Enable SPA navigation tracking | | data-debug | No | false | Enable console debug logs | | data-dnt | No | false | Respect Do Not Track setting |

Example with Options

<script 
  src="https://cdn.jsdelivr.net/npm/@aisearchindex/pixel/dist/aisearchindex.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:

import { AISearchIndex } from '@aisearchindex/pixel'

// Initialize with options
AISearchIndex.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
AISearchIndex.track()

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

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

Framework Examples

Next.js (App Router)

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

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

React (Vite / CRA)

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

Vue

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

Astro

---
// Layout.astro
---
<html>
  <head>
    <script 
      src="https://cdn.jsdelivr.net/npm/@aisearchindex/pixel/dist/aisearchindex.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":

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

Webflow

Go to Project Settings → Custom Code
Paste the script in Head Code or Footer Code

Shopify

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

Google Tag Manager

Create a new Custom HTML tag
Paste the script
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

Agentic AI Detection

The library includes client-side detection for browser-based AI agents:

import { detectAgenticAI, detectAgenticAIAsync } from '@aisearchindex/pixel'

// Synchronous detection (fast)
const result = detectAgenticAI()
console.log(result.detected)    // true/false
console.log(result.agent)       // 'Genspark', 'Manus', etc. or null
console.log(result.confidence)  // 'high', 'medium', 'low'
console.log(result.indicators)  // ['webdriver', 'no_plugins', etc.]

// Async detection (includes browser extension checks)
const fullResult = await detectAgenticAIAsync()

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:

Download the latest release
Host aisearchindex.min.js on your CDN
Update data-endpoint to point to your instance

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

Development

# Install dependencies
npm install

# Build all formats
npm run build

# Watch mode
npm run dev

# Check bundle sizes
npm run size

License

Built with care by AI Search Index - AI Search Analytics

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@aisearchindex/pixel

Features

Quick Start

Option 1: CDN (Recommended)

Option 2: npm

CDN Options

jsDelivr (Recommended)

unpkg

Self-hosted

Configuration

Script Attributes

Example with Options

Programmatic Usage

Framework Examples

Next.js (App Router)

React (Vite / CRA)

Vue

Astro

WordPress

Webflow

Shopify

Google Tag Manager

What Gets Tracked

Agentic AI Detection

Privacy

Browser Support

Self-Hosting

Development

License