@loamly/tracker 1.9.0 → 2.0.0

package/README.md

@@ -1,82 +1,181 @@
 # @loamly/tracker
 
-**Open-source AI traffic detection for websites.**
+**See every AI bot that visits your website — and what they tell users about you.**
 
-> See what AI tells your customers — and track when they click.
+ChatGPT, Claude, Perplexity, Gemini — know when they crawl your pages or refer traffic.
 
-[![npm version](https://img.shields.io/npm/v/@loamly/tracker.svg)](https://www.npmjs.com/package/@loamly/tracker)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm](https://img.shields.io/npm/v/@loamly/tracker)](https://www.npmjs.com/package/@loamly/tracker)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-Part of the [Loamly](https://github.com/loamly/loamly) open-source project.
+## Why This Exists
 
----
+**75-85% of AI-referred traffic is invisible** to traditional analytics. Users copy-paste from ChatGPT or type URLs from Perplexity — no referrer, no UTM, no attribution.
 
-## The Problem
+This tracker uses multiple detection methods to identify AI-influenced visits:
 
-When users copy URLs from ChatGPT, Claude, or Perplexity:
+| Method | Accuracy | What It Detects |
+|--------|----------|-----------------|
+| Navigation Timing API | 85% | Paste vs click (instant navigation = copy-paste) |
+| Focus/Blur Sequence | 80% | Paste pattern (focus → immediate navigation) |
+| Behavioral ML | 78% | Mouse patterns, scroll velocity, dwell time |
+| Agentic Browser Detection | 92% | CDP automation, Perplexity Comet DOM |
+| AI Referrer/UTM | 100% | Direct referrals from AI platforms |
 
-- ❌ No referrer header
-- ❌ No UTM parameters
-- ❌ Analytics shows "Direct Traffic"
-
-## The Solution
-
-Loamly detects AI-referred traffic with **75-85% accuracy** using:
-
-- 🔍 Referrer detection
-- ⏱️ Navigation Timing API (paste vs click)
-- 🧠 Behavioral signals
-- 📋 Zero-party surveys
+Combined with [@loamly/edge](../edge/) for server-side detection, you get **75-85% total accuracy**.
 
 ## Quick Start
 
-### Script Tag
+### Option 1: CDN (Recommended)
 
 ```html
-<script 
-  src="https://unpkg.com/@loamly/tracker" 
-  data-api-key="your-api-key"
-></script>
+<script src="https://cdn.jsdelivr.net/npm/@loamly/tracker@2/dist/loamly.iife.min.global.js"></script>
+<script>
+  Loamly.init({ apiKey: 'your-api-key' });
+</script>
 ```
 
-### NPM
+### Option 2: npm
 
 ```bash
 npm install @loamly/tracker
 ```
 
 ```typescript
-import loamly from '@loamly/tracker'
+import { loamly } from '@loamly/tracker';
+
+loamly.init({ apiKey: 'your-api-key' });
+```
+
+## Features
+
+### 🔍 Multi-Signal AI Detection
+
+```typescript
+// Check current detection results
+const ai = loamly.getAIDetection();
+console.log(ai);
+// { isAI: true, platform: 'chatgpt', confidence: 0.85, method: 'behavioral' }
+
+const timing = loamly.getNavigationTiming();
+console.log(timing);
+// { nav_type: 'likely_paste', confidence: 0.92, signals: ['instant_fetch_start'] }
+
+const behavioral = loamly.getBehavioralML();
+console.log(behavioral);
+// { classification: 'ai_influenced', humanProbability: 0.23, aiProbability: 0.77 }
+```
+
+### 📊 Advanced Behavioral Tracking
+
+- **Scroll Depth**: 30% chunk reporting (30%, 60%, 90%, 100%)
+- **Time Spent**: Active vs idle time, engagement detection
+- **Form Tracking**: HubSpot, Typeform, JotForm, native forms
+- **SPA Support**: Automatic History API detection
+
+### 🤖 Agentic Browser Detection
+
+Detects AI agents that browse on behalf of users:
+
+```typescript
+const agentic = loamly.getAgentic();
+console.log(agentic);
+// { 
+//   cometDOMDetected: true,      // Perplexity Comet overlay
+//   cdpDetected: false,           // Chrome DevTools Protocol
+//   mousePatterns: { teleportingClicks: 0 },
+//   agenticProbability: 0.85
+// }
+```
+
+### ⚡ Production Infrastructure
+
+- **Event Queue**: Batching, retry with exponential backoff, localStorage persistence
+- **Ping Service**: 30-second heartbeat for active sessions
+- **Beacon Fallback**: Reliable event delivery on page unload
+- **Offline Support**: Events queued when offline, synced when back
+
+## API Reference
+
+### `init(config)`
+
+Initialize the tracker with configuration.
+
+```typescript
+loamly.init({
+  apiKey: 'your-api-key',        // Required
+  apiHost: 'https://app.loamly.ai', // Optional: custom host
+  debug: true,                    // Optional: enable console logging
+  disableAutoPageview: false,     // Optional: disable auto pageview
+  disableBehavioral: false,       // Optional: disable behavioral tracking
+});
+```
+
+### `track(eventName, options?)`
+
+Track a custom event.
+
+```typescript
+loamly.track('button_click', {
+  properties: { buttonId: 'cta-hero' },
+});
+```
+
+### `conversion(eventName, revenue, currency?)`
+
+Track a conversion with revenue.
 
-loamly.init({ apiKey: 'your-api-key' })
-loamly.track('signup_started')
-loamly.conversion('purchase', 99.99)
+```typescript
+loamly.conversion('purchase', 99.99, 'USD');
 ```
 
-## API
+### `identify(userId, traits?)`
 
-| Method | Description |
-|--------|-------------|
-| `init(config)` | Initialize the tracker |
-| `pageview(url?)` | Track page view |
-| `track(event, options?)` | Track custom event |
-| `conversion(event, revenue, currency?)` | Track conversion |
-| `identify(userId, traits?)` | Identify user |
-| `getAIDetection()` | Get AI detection result |
-| `getNavigationTiming()` | Get paste vs click analysis |
+Identify a user for cross-session tracking.
+
+```typescript
+loamly.identify('user-123', {
+  email: 'user@example.com',
+  plan: 'pro',
+});
+```
+
+### `pageview(url?)`
+
+Manually track a pageview (useful for SPAs).
+
+```typescript
+loamly.pageview('/dashboard');
+```
 
 ## Privacy
 
-- 🍪 Cookie-free
-- 📍 No IP tracking
-- 🔒 GDPR compliant
+- **Cookie-free**: Uses localStorage for visitor/session ID
+- **GDPR-friendly**: No personal data stored by default
+- **Opt-out support**: Can be disabled via config
+- **Open source**: Audit the code yourself
 
-## Documentation
+## Combine with Edge Detection
 
-See [loamly.ai/docs](https://loamly.ai/docs) for full documentation.
+For 100% accurate detection of ChatGPT Agent Mode and other signed bots, combine with [@loamly/edge](../edge/):
+
+```
+┌─────────────────────────────────────────────┐
+│              @loamly/edge                   │
+│    Cloudflare Worker (server-side)          │
+│    → 100% for signed bots (RFC 9421)        │
+│    → 95% for all AI crawlers                │
+└─────────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────────┐
+│            @loamly/tracker                  │
+│      Browser tracker (client-side)          │
+│    → Paste detection, behavioral ML         │
+│    → Agentic browser detection              │
+└─────────────────────────────────────────────┘
+                    ↓
+        75-85% total detection accuracy
+```
 
 ## License
 
 MIT © [Loamly](https://loamly.ai)
-
-