@superlines/pixel
v1.0.0
Published
Lightweight AI search analytics pixel for tracking LLM bot traffic and human visitors
Maintainers
ihmissutiReadme
@superlines/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/@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
npm install @superlines/pixelimport { Superlines } from '@superlines/pixel'
Superlines.init({ trackingId: 'YOUR_TRACKING_ID' })CDN Options
jsDelivr (Recommended)
<!-- 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/[email protected]/dist/superlines.min.js" data-tid="YOUR_TRACKING_ID" async></script>unpkg
<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 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
<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:
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)
// 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)
// 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
<!-- 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
---
// 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":
<script
src="https://cdn.jsdelivr.net/npm/@superlines/pixel/dist/superlines.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
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
superlines.min.json your CDN - Update
data-endpointto point to your Superlines instance
<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
# Install dependencies
npm install
# Build all formats
npm run build
# Watch mode
npm run dev
# Check bundle sizes
npm run sizeLicense
MIT © Superlines
Built with ❤️ by Superlines - AI Search Analytics