@datalyr/web 1.2.0 → 1.2.2

package/README.md

@@ -1,493 +1,496 @@
 # @datalyr/web
 
-The official Datalyr Web SDK for browser-based analytics. Track user behavior, measure conversions, and understand your customer journey with enterprise-grade analytics.
+Browser analytics and attribution SDK for web applications. Track events, identify users, and capture attribution data across your website.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [How It Works](#how-it-works)
+- [Configuration](#configuration)
+- [Event Tracking](#event-tracking)
+  - [Custom Events](#custom-events)
+  - [Page Views](#page-views)
+  - [E-Commerce Events](#e-commerce-events)
+- [User Identity](#user-identity)
+  - [Anonymous ID](#anonymous-id)
+  - [Identifying Users](#identifying-users)
+  - [User Properties](#user-properties)
+- [Attribution](#attribution)
+  - [Automatic Capture](#automatic-capture)
+  - [Custom Parameters](#custom-parameters)
+- [Event Queue](#event-queue)
+- [Offline Support](#offline-support)
+- [Privacy and Consent](#privacy-and-consent)
+- [SPA Support](#spa-support)
+- [Container Scripts](#container-scripts)
+- [Framework Integration](#framework-integration)
+  - [React](#react)
+  - [Vue](#vue)
+  - [Next.js](#nextjs)
+- [TypeScript](#typescript)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
 
-[![npm version](https://img.shields.io/npm/v/@datalyr/web.svg)](https://www.npmjs.com/package/@datalyr/web)
-[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@datalyr/web)](https://bundlephobia.com/package/@datalyr/web)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
-[![License](https://img.shields.io/npm/l/@datalyr/web.svg)](https://github.com/datalyr/web/blob/main/LICENSE)
-
-## Features
-
-- **Zero Configuration** - Start tracking with just your workspace ID
-- **Lightweight** - ~15KB minified + gzipped with zero dependencies
-- **Privacy First** - GDPR compliant with built-in consent management
-- **Smart Batching** - Optimized network usage with intelligent event queuing
-- **Cross-Platform** - Works on all modern browsers including mobile
-- **Offline Support** - Events are queued and sent when connection restored
-- **Attribution Tracking** - Automatic UTM and click ID capture
-- **Session Management** - Automatic session tracking with configurable timeout
-- **TypeScript Support** - Full type definitions included
-- **Extensible** - Plugin system for custom functionality
-- **Container Scripts** - Securely manage third-party pixels and tracking scripts
+---
 
-## Choosing the Right Installation Method
+## Installation
 
-Datalyr offers two installation methods. Choose based on your needs:
+### NPM Package
 
-### Script Tag (Recommended for Most Cases)
+```bash
+npm install @datalyr/web
+```
 
-**Use when:** Simple setup, zero bundle size, no build step needed
+### Script Tag
 
 ```html
-<script defer src="https://track.datalyr.com/container.js"
+<script defer src="https://track.datalyr.com/dl.js"
         data-workspace-id="YOUR_WORKSPACE_ID"></script>
 ```
 
-**Pros:**
-- Zero bundle size (external script)
-- No npm install needed
-- Works in any HTML page
-- Automatic initialization
-- Perfect for Next.js, React, Vue
-
-**API Usage:**
-```javascript
-// Available globally after script loads
-window.datalyr.track('event_name', { key: 'value' })
-window.datalyr.identify('user_123', { email: 'user@example.com' })
-window.datalyr.getVisitorId()
-```
-
-[See Script Tag Documentation →](https://docs.datalyr.com/installation/script-tag)
+The script tag loads externally (zero bundle size) and auto-initializes. Use `window.datalyr` to access the SDK.
 
 ---
 
-### NPM Package (For TypeScript/Bundlers)
+## Quick Start
 
-**Use when:** You need TypeScript support, ES modules, or tree-shaking
+```javascript
+import datalyr from '@datalyr/web';
 
-```bash
-npm install @datalyr/web
-```
+// Initialize
+datalyr.init({
+  workspaceId: 'YOUR_WORKSPACE_ID'
+});
 
-**Pros:**
-- Full TypeScript definitions
-- ES module imports
-- Tree-shaking support
-- Better IDE autocomplete
+// Track events
+datalyr.track('button_clicked', { button: 'signup' });
 
-**API Usage:**
-```javascript
-import datalyr from '@datalyr/web'
+// Identify users
+datalyr.identify('user_123', { email: 'user@example.com' });
 
-datalyr.init({ workspaceId: 'YOUR_WORKSPACE_ID' })
-datalyr.track('event_name', { key: 'value' })
-datalyr.identify('user_123', { email: 'user@example.com' })
+// Track page views
+datalyr.page('Pricing', { variant: 'A' });
 ```
 
 ---
 
-### Important: Don't Mix Both Methods
+## How It Works
 
-Choose **one** installation method. Using both can cause conflicts:
+The SDK collects events and sends them to the Datalyr backend for analytics and attribution.
 
-```html
-<!-- DON'T DO THIS -->
-<script src="https://track.datalyr.com/container.js"></script>
-<script>
-  import datalyr from '@datalyr/web'  // Both methods at once!
-  datalyr.init({...})
-</script>
-```
+### Data Flow
 
-## Installation
+1. Events are created with `track()`, `page()`, or `identify()`
+2. Each event includes device info, session data, and attribution parameters
+3. Events are queued locally and sent in batches
+4. If offline, events are stored and sent when connectivity returns
+5. Events are processed server-side for analytics and attribution reporting
 
-```bash
-npm install @datalyr/web
-# or
-yarn add @datalyr/web
-# or
-pnpm add @datalyr/web
-```
+### Event Payload
 
-## Quick Start
+Every event includes:
 
 ```javascript
-import datalyr from '@datalyr/web';
+{
+  event: 'purchase',              // Event name
+  properties: { ... },            // Custom properties
 
-// Initialize the SDK with your workspace ID
-datalyr.init({
-  workspaceId: 'YOUR_WORKSPACE_ID'
-});
+  // Identity
+  anonymous_id: 'anon_xxxxx',     // Persistent browser ID
+  user_id: 'user_123',            // Set after identify()
+  session_id: 'sess_xxxxx',       // Current session
 
-// Track an event
-datalyr.track('Button Clicked', {
-  button_name: 'Sign Up',
-  location: 'Header'
-});
+  // Context
+  page_url: 'https://example.com/pricing',
+  page_title: 'Pricing',
+  referrer: 'https://google.com',
 
-// Identify a user
-datalyr.identify('user_123', {
-  email: 'user@example.com',
-  name: 'John Doe',
-  plan: 'premium'
-});
+  // Attribution (if captured)
+  utm_source: 'facebook',
+  fbclid: 'abc123',
+
+  // Timestamps
+  timestamp: '2024-01-15T10:30:00Z',
+}
 ```
 
-## Core Methods
+---
 
-### Initialization
+## Configuration
 
 ```javascript
-import datalyr from '@datalyr/web';
-
-// Initialize the SDK with configuration
 datalyr.init({
-  workspaceId: 'YOUR_WORKSPACE_ID',
+  // Required
+  workspaceId: string,
+
+  // Features
+  debug?: boolean,                       // Console logging
+  trackPageViews?: boolean,              // Track initial page view (default: true)
+  trackSPA?: boolean,                    // Track SPA route changes (default: true)
+
+  // Event Queue
+  batchSize?: number,                    // Events per batch (default: 10)
+  flushInterval?: number,                // Send interval ms (default: 5000)
+
+  // Session
+  sessionTimeout?: number,               // Session timeout ms (default: 1800000 / 30 min)
+
+  // Privacy
+  privacyMode?: 'standard' | 'strict',   // Privacy level (default: 'standard')
+  respectDoNotTrack?: boolean,           // Honor browser DNT (default: false)
+  respectGlobalPrivacyControl?: boolean, // Honor GPC (default: true)
+
+  // Cookies
+  cookieDomain?: string | 'auto',        // Cookie domain (default: 'auto')
 
-  // Optional configuration
-  debug: false,                             // Enable debug logging
-  sessionTimeout: 1800000,                 // 30 minutes
-  privacyMode: 'standard',                 // 'standard' or 'strict'
-  respectDoNotTrack: false,                // Honor browser DNT
-  respectGlobalPrivacyControl: true,       // Honor GPC
-  cookieDomain: 'auto',                    // Auto-detect for subdomains
-  trackSPA: true,                          // Track SPA route changes
-  trackPageViews: true,                    // Track initial page view
-  enableContainer: true                    // Enable container script loading
+  // Container
+  enableContainer?: boolean,             // Load container scripts (default: true)
+
+  // Custom
+  trackedParams?: string[],              // Additional URL params to track
+  plugins?: Plugin[],                    // Custom plugins
 });
 ```
 
-### Track Events
+---
+
+## Event Tracking
+
+### Custom Events
 
-Track custom events with properties:
+Track any action on your website:
 
 ```javascript
 // Simple event
-datalyr.track('Video Played');
+datalyr.track('signup_started');
 
 // Event with properties
-datalyr.track('Product Viewed', {
-  product_id: 'SKU-123',
-  product_name: 'Premium Widget',
-  category: 'Electronics',
-  price: 99.99,
-  currency: 'USD'
+datalyr.track('product_viewed', {
+  product_id: 'SKU123',
+  product_name: 'Blue Shirt',
+  price: 29.99,
+  currency: 'USD',
+  category: 'Apparel',
 });
 
-// E-commerce events
-datalyr.track('Purchase', {
-  order_id: 'ORD-456',
-  total: 299.99,
-  currency: 'USD',
-  items: [
-    { product_id: 'SKU-123', quantity: 2, price: 99.99 },
-    { product_id: 'SKU-456', quantity: 1, price: 100.01 }
-  ]
+// Event with value
+datalyr.track('level_completed', {
+  level: 5,
+  score: 1250,
+  time_seconds: 120,
 });
 ```
 
-### Identify Users
+### Page Views
 
-Associate events with users:
+Track navigation:
 
 ```javascript
-// Identify with user ID only
-datalyr.identify('user_123');
+// Track current page
+datalyr.page();
 
-// Identify with traits
-datalyr.identify('user_123', {
-  email: 'user@example.com',
-  name: 'John Doe',
-  firstName: 'John',
-  lastName: 'Doe',
-  phone: '+1234567890',
-  plan: 'premium',
-  createdAt: '2024-01-01'
-});
+// Track with name
+datalyr.page('Pricing');
 
-// Update user traits without changing ID
-datalyr.identify(null, {
-  plan: 'enterprise',
-  company: 'Acme Corp'
+// Track with properties
+datalyr.page('Product Details', {
+  product_id: 'SKU123',
+  source: 'search',
 });
 ```
 
-### Page Tracking
+### E-Commerce Events
 
-Track page views:
+Standard e-commerce tracking:
 
 ```javascript
-// Track current page
-datalyr.page();
+// View product
+datalyr.track('Product Viewed', {
+  product_id: 'SKU123',
+  product_name: 'Blue Shirt',
+  price: 29.99,
+  currency: 'USD'
+});
 
-// Track with custom properties
-datalyr.page({
-  title: 'Pricing Page',
-  category: 'Marketing',
-  author: 'Marketing Team'
+// Add to cart
+datalyr.track('Add to Cart', {
+  product_id: 'SKU123',
+  quantity: 1,
+  price: 29.99
 });
 
-// Track with page name
-datalyr.page('Pricing', {
-  plan: 'premium',
-  variant: 'A'
+// Start checkout
+datalyr.track('Checkout Started', {
+  cart_value: 59.98,
+  currency: 'USD',
+  item_count: 2
+});
+
+// Complete purchase
+datalyr.track('Purchase', {
+  order_id: 'ORD-456',
+  total: 59.98,
+  currency: 'USD',
+  items: [
+    { product_id: 'SKU123', quantity: 2, price: 29.99 }
+  ]
 });
 ```
 
-### Managing Identity
+---
 
-```javascript
-// Get current user IDs
-const anonymousId = datalyr.getAnonymousId();
-const userId = datalyr.getUserId();
-const distinctId = datalyr.getDistinctId();
+## User Identity
 
-// Reset identity (for logout)
-datalyr.reset();
+### Anonymous ID
+
+Every visitor gets a persistent anonymous ID on first visit:
 
-// Create alias (link anonymous to identified user)
-datalyr.alias('user_123');
+```javascript
+const anonymousId = datalyr.getAnonymousId();
+// 'anon_a1b2c3d4e5f6'
 ```
 
-### User Consent
+This ID:
+- Persists across browser sessions
+- Links events before and after user identification
+- Can be passed to your backend for server-side attribution
+
+### Identifying Users
 
-Manage user privacy preferences:
+Link the anonymous ID to a known user:
 
 ```javascript
-// Opt user out of tracking
-datalyr.optOut();
+datalyr.identify('user_123', {
+  email: 'user@example.com',
+});
+```
 
-// Opt user back in
-datalyr.optIn();
+After `identify()`:
+- All future events include `user_id`
+- Historical anonymous events can be linked server-side
+- Attribution data is preserved on the user
 
-// Check opt-out status
-const isOptedOut = datalyr.isOptedOut();
+### User Properties
 
-// Set consent preferences
-datalyr.setConsent({
-  analytics: true,
-  marketing: false,
-  preferences: true,
-  sale: false  // CCPA "Do Not Sell"
+Pass any user attributes:
+
+```javascript
+datalyr.identify('user_123', {
+  // Standard fields
+  email: 'user@example.com',
+  name: 'John Doe',
+  phone: '+1234567890',
+
+  // Custom fields
+  plan: 'premium',
+  company: 'Acme Inc',
+  signup_date: '2024-01-15',
 });
 ```
 
-### Session Management
+### Logout
+
+Clear user data on logout:
 
 ```javascript
-// Get current session ID
-const sessionId = datalyr.getSessionId();
+datalyr.reset();
+```
 
-// Start new session
-datalyr.startNewSession();
+This:
+- Clears the user ID
+- Starts a new session
+- Keeps the anonymous ID (same browser)
 
-// Get session data
-const sessionData = datalyr.getSessionData();
-```
+---
 
-## Advanced Features
+## Attribution
 
-### Event Priority
+### Automatic Capture
 
-Important events like purchases are automatically prioritized for faster delivery:
+The SDK captures attribution from URLs and referrers:
 
 ```javascript
-// Important conversion events
-datalyr.track('Purchase', { value: 99.99 });
-datalyr.track('Signup', { plan: 'premium' });
-datalyr.track('Subscribe', { plan: 'annual' });
-
-// E-commerce events
-datalyr.track('Add to Cart', { product_id: 'SKU-123' });
-datalyr.track('Begin Checkout', { cart_value: 199.99 });
+const attribution = datalyr.getAttributionData();
 ```
 
-### Attribution Tracking
+Captured parameters:
 
-The SDK automatically captures:
-- UTM parameters (utm_source, utm_medium, utm_campaign, utm_term, utm_content)
-- Click IDs (gclid, fbclid, ttclid, msclkid, twclid, li_fat_id)
-- Referrer information
-- Landing page
-- Customer journey touchpoints
+| Type | Parameters |
+|------|------------|
+| UTM | `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` |
+| Click IDs | `fbclid`, `gclid`, `ttclid`, `twclid`, `li_fat_id`, `msclkid` |
+| Referrer | `referrer`, `landing_page` |
 
-```javascript
-// Attribution data is automatically added to events
-datalyr.track('Signup');
-// Includes: utm_source, utm_medium, first_touch_source, last_touch_source, etc.
+Attribution is automatically included in all events and supports:
+- First-touch attribution (90-day window)
+- Last-touch attribution
+- Customer journey tracking (up to 30 touchpoints)
 
-// Track custom URL parameters
-import datalyr from '@datalyr/web';
+### Custom Parameters
 
+Track additional URL parameters:
+
+```javascript
 datalyr.init({
   workspaceId: 'YOUR_WORKSPACE_ID',
   trackedParams: ['ref', 'affiliate_id', 'promo_code']
 });
 ```
 
-### SPA Support
+---
 
-For single-page applications:
+## Event Queue
 
-```javascript
-import datalyr from '@datalyr/web';
+Events are batched for efficiency.
+
+### Configuration
 
+```javascript
 datalyr.init({
   workspaceId: 'YOUR_WORKSPACE_ID',
-  trackSPA: true  // Auto-track route changes (default: true)
-});
-
-// Manual route tracking
-datalyr.page('Product Details', {
-  product_id: 'SKU-123'
+  batchSize: 10,           // Send when 10 events queued
+  flushInterval: 5000,     // Or every 5 seconds
 });
 ```
 
-### Privacy Modes
+### Manual Flush
 
-Control data collection:
+Send all queued events immediately:
 
 ```javascript
-import datalyr from '@datalyr/web';
+await datalyr.flush();
+```
 
-// Standard mode (default) - balanced privacy
-datalyr.init({
-  workspaceId: 'YOUR_WORKSPACE_ID',
-  privacyMode: 'standard'
-});
+### Priority Events
 
-// Or strict mode - minimal data collection
-datalyr.init({
-  workspaceId: 'YOUR_WORKSPACE_ID',
-  privacyMode: 'strict'
-});
-```
+Important events like `Purchase`, `Signup`, and `Subscribe` are automatically prioritized for faster delivery.
 
-### Offline Support
+---
 
-Events are automatically saved when offline and sent when connection is restored:
+## Offline Support
+
+When the browser is offline:
+- Events are stored locally
+- Queue persists across page refreshes
+- Events are sent when connectivity returns
 
 ```javascript
 // Events work seamlessly offline
 datalyr.track('Button Clicked'); // Automatically queued if offline
 
-// Manually flush pending events
+// Manually flush when ready
 await datalyr.flush();
 ```
 
-### Cross-Subdomain Tracking
+---
+
+## Privacy and Consent
 
-Automatically track users across subdomains:
+### Opt Out
 
 ```javascript
-import datalyr from '@datalyr/web';
+// Opt user out of tracking
+datalyr.optOut();
+
+// Opt user back in
+datalyr.optIn();
+
+// Check status
+const isOptedOut = datalyr.isOptedOut();
+```
+
+### Consent Preferences
 
-// Auto-detect domain for *.example.com
+```javascript
+datalyr.setConsent({
+  analytics: true,
+  marketing: false,
+  preferences: true,
+  sale: false  // CCPA "Do Not Sell"
+});
+```
+
+### Privacy Modes
+
+```javascript
+// Standard mode (default)
 datalyr.init({
   workspaceId: 'YOUR_WORKSPACE_ID',
-  cookieDomain: 'auto'  // Default
+  privacyMode: 'standard'
 });
 
-// Or set explicitly
+// Strict mode - minimal data collection
 datalyr.init({
   workspaceId: 'YOUR_WORKSPACE_ID',
-  cookieDomain: '.example.com'
+  privacyMode: 'strict'
 });
 ```
 
-### Container Scripts
+---
 
-The SDK can automatically load and manage third-party tracking scripts with built-in security:
+## SPA Support
 
-```javascript
-import datalyr from '@datalyr/web';
+For single-page applications:
 
+```javascript
 datalyr.init({
   workspaceId: 'YOUR_WORKSPACE_ID',
-  enableContainer: true  // Default: true
+  trackSPA: true  // Auto-track route changes (default: true)
 });
 
-// Container scripts are loaded automatically based on your
-// configuration in the Datalyr dashboard
-
-// Manually trigger a custom script
-datalyr.loadScript('custom-script-id');
-
-// Get list of loaded scripts
-const loadedScripts = datalyr.getLoadedScripts();
+// Manual route tracking
+datalyr.page('Product Details', {
+  product_id: 'SKU-123'
+});
 ```
 
-The container manager supports:
-- **Third-party pixels**: Meta (Facebook), Google, TikTok
-- **Custom scripts**: Inline JavaScript or external scripts
-- **Tracking pixels**: Image-based tracking pixels
-- **Conditional loading**: Based on URL, device type, etc.
-- **Frequency control**: Once per session, once per page, or always
-
-**Security Features:**
-- HTTPS-only script loading (except localhost)
-- XSS protection with pattern detection
-- URL validation and protocol blocking
-- CSP nonce support for inline scripts
-- Automatic async loading for better performance
-
-### Plugins
+---
 
-Extend SDK functionality:
+## Container Scripts
 
-```javascript
-import datalyr from '@datalyr/web';
+Container scripts manage third-party tracking pixels (Meta, Google, TikTok) configured in your Datalyr dashboard.
 
-// Create a plugin
-const myPlugin = {
-  name: 'my-plugin',
+### Script Tag Installation
 
-  initialize(datalyr) {
-    console.log('Plugin initialized');
-  },
+For container scripts, use the container endpoint:
 
-  track(eventName, properties) {
-    console.log('Event tracked:', eventName);
-  },
+```html
+<script defer src="https://track.datalyr.com/container.js"
+        data-workspace-id="YOUR_WORKSPACE_ID"></script>
+```
 
-  identify(userId, traits) {
-    console.log('User identified:', userId);
-  },
+This loads your configured pixels and tracking scripts automatically.
 
-  page(properties) {
-    console.log('Page tracked');
-  }
-};
+### NPM SDK with Containers
 
-// Register plugin during initialization
+```javascript
 datalyr.init({
   workspaceId: 'YOUR_WORKSPACE_ID',
-  plugins: [myPlugin]
+  enableContainer: true  // Default: true
 });
-```
 
-## TypeScript Support
-
-Full TypeScript definitions are included:
-
-```typescript
-import datalyr, { EventProperties, UserTraits } from '@datalyr/web';
+// Manually trigger a script
+datalyr.loadScript('custom-script-id');
 
-// Initialize the SDK
-datalyr.init({
-  workspaceId: 'YOUR_WORKSPACE_ID'
-});
+// Get loaded scripts
+const scripts = datalyr.getLoadedScripts();
+```
 
-// Type-safe event properties
-const properties: EventProperties = {
-  product_id: 'SKU-123',
-  price: 99.99,
-  quantity: 2
-};
+### Supported Pixels
 
-datalyr.track('Product Added', properties);
+- Meta (Facebook) Pixel
+- Google Analytics / Google Ads
+- TikTok Pixel
+- Custom scripts and tracking pixels
 
-// Type-safe user traits
-const traits: UserTraits = {
-  email: 'user@example.com',
-  name: 'John Doe',
-  plan: 'premium'
-};
+Security features:
+- HTTPS-only script loading
+- XSS protection
+- URL validation
+- CSP nonce support
 
-datalyr.identify('user_123', traits);
-```
+---
 
 ## Framework Integration
 
@@ -505,9 +508,7 @@ function App() {
   }, []);
 
   const handleClick = () => {
-    datalyr.track('Button Clicked', {
-      button_name: 'CTA'
-    });
+    datalyr.track('Button Clicked', { button_name: 'CTA' });
   };
 
   return <button onClick={handleClick}>Click Me</button>;
@@ -552,14 +553,6 @@ export function AnalyticsProvider({ children }) {
       workspaceId: process.env.NEXT_PUBLIC_DATALYR_WORKSPACE_ID,
       debug: process.env.NODE_ENV === 'development'
     });
-
-    // Verify initialization
-    console.log('Datalyr initialized');
-    console.log('Session ID:', datalyr.getSessionId());
-    console.log('Anonymous ID:', datalyr.getAnonymousId());
-
-    // Track initial page view
-    datalyr.page();
   }, []);
 
   return children;
@@ -581,518 +574,84 @@ export default function RootLayout({ children }) {
 }
 ```
 
-## Authentication & Attribution Tracking
-
-### Critical: Client-Side Identification for Attribution
-
-When implementing authentication flows (login, signup, OAuth), you **MUST** call identify on the client-side (browser) to preserve attribution data. Server-side identification creates new sessions and loses all attribution context.
-
-#### The Problem with Server-Side Identify
-
-```javascript
-// ❌ WRONG - Server-side identify breaks attribution
-app.post('/api/login', async (req, res) => {
-  const user = await authenticate(email, password);
-
-  // This creates a NEW session without attribution data!
-  await serverAnalytics.identify({
-    userId: user.id,
-    traits: { email: user.email }
-  });
-
-  res.json({ userId: user.id });
-});
-// Result: Lost UTM params, fbclid, gclid, referrer - all gone!
-```
-
-#### The Correct Solution
-
-```javascript
-// ✅ CORRECT - Client-side identification preserves attribution
-// React/Next.js example
-function LoginPage() {
-  const handleLogin = async () => {
-    // 1. Authenticate on server
-    const response = await fetch('/api/login', {
-      method: 'POST',
-      body: JSON.stringify({ email, password })
-    });
-
-    const { userId, email, name } = await response.json();
-
-    // 2. Identify in browser - this preserves attribution!
-    datalyr.identify(userId, {
-      email: email,
-      name: name,
-      login_method: 'email'
-    });
-
-    // 3. Then redirect
-    router.push('/dashboard');
-  };
-}
-
-// Server endpoint - NO identify, just auth
-app.post('/api/login', async (req, res) => {
-  const user = await authenticate(email, password);
-
-  // Just return user data for client-side identify
-  res.json({
-    userId: user.id,
-    email: user.email,
-    name: user.name
-  });
-});
-```
-
-### Why Client-Side Identification Matters
-
-1. **Attribution Preserved**: UTM params, fbclid, gclid, referrer all stay linked to the user
-2. **Session Continuity**: Links anonymous session (with all its context) to identified user
-3. **Cookie Access**: Can read and maintain browser session data
-4. **Accurate Journey**: Tracks the complete anonymous → identified user journey
-
-### Implementation Checklist
-
-Ensure you call identify **client-side** in these scenarios:
-
-- [ ] **After Signup Success**: When account creation API returns success
-- [ ] **After Login Success**: When authentication API returns success
-- [ ] **After OAuth Redirect**: When returning from OAuth provider
-- [ ] **After Magic Link Click**: When magic link is validated
-- [ ] **On App Load**: If user session exists, re-identify
-- [ ] **After Email Verification**: When user verifies their email
-- [ ] **Session Restore**: When detecting existing authenticated session
-
-### Example: Complete OAuth Implementation
-
-```javascript
-// Client-side: After OAuth redirect
-useEffect(() => {
-  // Check if we just came back from OAuth
-  if (window.location.search.includes('oauth=success')) {
-    // Get user data from your API/session
-    fetch('/api/me')
-      .then(res => res.json())
-      .then(user => {
-        // Identify in browser - preserves attribution!
-        datalyr.identify(user.id, {
-          email: user.email,
-          name: user.name,
-          auth_method: 'google',
-          signup_source: localStorage.getItem('signup_source') || 'organic'
-        });
-
-        // Track the appropriate event
-        if (user.isNewUser) {
-          datalyr.track('Signup Completed', { method: 'oauth' });
-        } else {
-          datalyr.track('Login Successful', { method: 'oauth' });
-        }
-      });
-  }
-}, []);
-
-// Server-side: OAuth callback - NO identify!
-export async function GET(request: Request) {
-  const { user } = await validateOAuthCallback(request);
-
-  const existingUser = await getUserByEmail(user.email);
-
-  if (existingUser) {
-    // Set session, but DON'T identify
-    await createSession(existingUser.id);
-    return redirect('/dashboard?oauth=success');
-  } else {
-    // Create user, but DON'T identify
-    const newUser = await createUser(user);
-    await createSession(newUser.id);
-    return redirect('/dashboard?oauth=success&new=true');
-  }
-}
-```
-
-### Server-Side Events (Different from Identify!)
-
-Use server-side for **tracking events** with userId (not identify):
-
-```javascript
-// ✅ CORRECT - Server-side events with userId
-// Stripe webhook example
-app.post('/webhook/stripe', async (req, res) => {
-  const event = stripe.webhooks.constructEvent(req.body, sig, secret);
-
-  if (event.type === 'checkout.session.completed') {
-    const session = event.data.object;
-
-    // Track purchase event with userId (NOT identify)
-    await analytics.track({
-      userId: session.client_reference_id,  // Your user ID
-      event: 'Purchase Completed',
-      properties: {
-        amount: session.amount_total / 100,
-        currency: session.currency,
-        plan: session.metadata.plan
-      }
-    });
-  }
-});
-```
-
-### What Happens with Server-Side Identify (Wrong!)
-
-If you identify server-side:
-- **Lost Attribution**: New session created, no UTM params or click IDs
-- **Broken Journey**: Can't link anonymous browsing to identified user
-- **Multiple Sessions**: Each server identify creates disconnected session
-- **No Context**: Missing referrer, landing page, device info
-
-## Best Practices
-
-### 1. Initialize Early
-Initialize the SDK as early as possible in your application lifecycle:
-
-```javascript
-// In your main entry file
-import datalyr from '@datalyr/web';
-
-// Initialize before other code
-datalyr.init({
-  workspaceId: 'YOUR_WORKSPACE_ID'
-});
-
-// Your app code...
-```
-
-### 2. Use Consistent Event Naming
-Adopt a naming convention for your events:
+---
 
-```javascript
-// Good: Consistent, descriptive names
-datalyr.track('Product Viewed');
-datalyr.track('Cart Updated');
-datalyr.track('Checkout Started');
-
-// Avoid: Inconsistent naming
-datalyr.track('view_product');
-datalyr.track('Cart-Update');
-datalyr.track('CHECKOUT_START');
-```
+## TypeScript
 
-### 3. Include Relevant Properties
-Add properties that will help with analysis:
+```typescript
+import datalyr, { EventProperties, UserTraits } from '@datalyr/web';
 
-```javascript
-// Good: Rich context
-datalyr.track('Product Viewed', {
+// Type-safe event properties
+const properties: EventProperties = {
   product_id: 'SKU-123',
-  product_name: 'Premium Widget',
-  category: 'Electronics',
   price: 99.99,
-  currency: 'USD',
-  in_stock: true,
-  view_type: 'quick_view'
-});
-
-// Avoid: Missing context
-datalyr.track('Product Viewed', {
-  id: '123'
-});
-```
-
-### 4. ALWAYS Identify in the Browser (Not Server)
-This is critical for attribution:
-
-```javascript
-// ✅ CORRECT - Browser identification
-async function handleLogin(email, password) {
-  const response = await fetch('/api/login', {
-    method: 'POST',
-    body: JSON.stringify({ email, password })
-  });
-
-  const user = await response.json();
-
-  // Identify in browser - preserves attribution!
-  datalyr.identify(user.id, {
-    email: user.email,
-    name: user.name,
-    plan: user.subscription
-  });
-}
+  quantity: 2
+};
 
-// ❌ WRONG - Server identification
-// This breaks attribution tracking!
-app.post('/api/login', async (req, res) => {
-  const user = await authenticate(req.body);
+datalyr.track('Product Added', properties);
 
-  // DON'T DO THIS - Creates new session
-  await serverAnalytics.identify(user.id, {
-    signup_date: new Date().toISOString()
-  });
+// Type-safe user traits
+const traits: UserTraits = {
+  email: 'user@example.com',
+  name: 'John Doe',
+  plan: 'premium'
+};
 
-  res.json({ success: true });
-});
+datalyr.identify('user_123', traits);
 ```
 
-### 5. Handle Errors Gracefully
-The SDK handles errors internally, but you can add your own error tracking:
-
-```javascript
-window.addEventListener('error', (event) => {
-  datalyr.track('JavaScript Error', {
-    message: event.message,
-    source: event.filename,
-    line: event.lineno,
-    column: event.colno,
-    error: event.error?.toString()
-  });
-});
-```
+---
 
 ## Troubleshooting
 
-### Events Not Showing in Dashboard?
+### Events not appearing
 
-**Step 1: Verify SDK is initialized**
-```javascript
-import datalyr from '@datalyr/web'
+1. Check workspace ID is correct
+2. Enable `debug: true`
+3. Verify `datalyr.getAnonymousId()` returns a value
+4. Check Network tab for requests to `ingest.datalyr.com`
+5. Disable ad blockers
 
-// Check these return values
-console.log('Anonymous ID:', datalyr.getAnonymousId())  // Should return "anon_xxxxx"
-console.log('Session ID:', datalyr.getSessionId())      // Should return "sess_xxxxx"
-```
-
-If these return `undefined`, the SDK isn't initialized properly.
+### SDK not initialized
 
-**Step 2: Check for errors**
 ```javascript
-console.log('Errors:', datalyr.getErrors())  // Should be empty [] or show errors
+// Check initialization
+console.log('Anonymous ID:', datalyr.getAnonymousId());
+console.log('Session ID:', datalyr.getSessionId());
+console.log('Errors:', datalyr.getErrors());
 ```
 
-**Step 3: Enable debug mode**
-```javascript
-datalyr.init({
-  workspaceId: 'YOUR_WORKSPACE_ID',
-  debug: true  // Shows [Datalyr] logs in console
-})
-```
-
-**Step 4: Verify network requests**
-1. Open DevTools → Network tab
-2. Filter by "ingest"
-3. Track a test event: `datalyr.track('test', {})`
-4. You should see POST to `ingest.datalyr.com`
-
-### Common Errors
-
-**"Cannot find module '@datalyr/web'"**
-- Run `npm install @datalyr/web`
-- Restart your dev server
-
-**"process.env.NEXT_PUBLIC_DATALYR_WORKSPACE_ID is undefined"**
-- Create `.env.local` file in project root
-- Add: `NEXT_PUBLIC_DATALYR_WORKSPACE_ID=your_id`
-- Restart dev server (required for env changes)
-
-**"datalyr.getAnonymousId() returns undefined"**
-- You're calling it during SSR (server-side rendering)
-- Make sure you're in a Client Component with `'use client'`
-- Call it inside `useEffect` or after component mounts
-
-**Events tracked but not in dashboard**
-- Verify workspace ID matches your dashboard
-- Events may take 1-2 minutes to appear
-- Check Network tab - requests should return 200 OK
-- Check if ad blocker is enabled (disable it)
-
-### Script Tag vs SDK Confusion
-
-**If you're using the script tag:**
-```javascript
-// Check if loaded
-window.datalyr._isLoaded        // Should be true
-window.datalyr.getVisitorId()   // Should return ID
-
-// Use object methods, not function calls
-window.datalyr.track('event', {})     // ✅ Correct
-window.datalyr("track", "event", {})  // ❌ Wrong
-```
-
-**If you're using the NPM SDK:**
-```javascript
-import datalyr from '@datalyr/web'
-
-// Check if loaded
-datalyr.getAnonymousId()  // Should return ID
-datalyr.getSessionId()    // Should return ID
-```
+If these return `undefined`, the SDK isn't initialized.
 
-## Migration from Script Tag
+### Next.js SSR issues
 
-If you're currently using the Datalyr script tag and want to switch to the NPM package:
+Make sure you're calling SDK methods client-side only:
 
-### Before (Script Tag):
-```html
-<!-- In your HTML -->
-<script defer src="https://track.datalyr.com/container.js"
-        data-workspace-id="YOUR_WORKSPACE_ID"></script>
-```
-
-```javascript
-// In your JavaScript
-window.datalyr.track('Button Clicked', {
-  button_name: 'Sign Up'
-});
-
-window.datalyr.identify('user_123', {
-  email: 'user@example.com'
-});
-```
-
-### After (NPM SDK):
-```javascript
-// Remove the script tag from your HTML
-
-// Install the package
-// npm install @datalyr/web
+```jsx
+'use client';
 
-// In your app initialization
+import { useEffect } from 'react';
 import datalyr from '@datalyr/web';
 
-datalyr.init({
-  workspaceId: 'YOUR_WORKSPACE_ID'
-});
-
-// In your components
-datalyr.track('Button Clicked', {
-  button_name: 'Sign Up'
-});
-
-datalyr.identify('user_123', {
-  email: 'user@example.com'
-});
+useEffect(() => {
+  // SDK methods only work in browser
+  datalyr.init({ workspaceId: '...' });
+}, []);
 ```
 
-**Note:** Most users should stay with the script tag unless they specifically need TypeScript support or ES module imports. The script tag has zero bundle size and works perfectly with Next.js, React, and Vue.
-
-## API Comparison: Script Tag vs NPM SDK
-
-| Feature | Script Tag | NPM SDK |
-|---------|-----------|---------|
-| **Installation** | Add `<script>` to HTML | `npm install @datalyr/web` |
-| **Bundle Size** | 0 (external) | ~15KB |
-| **TypeScript** | No types | ✅ Full types |
-| **Import** | `window.datalyr` | `import datalyr from '@datalyr/web'` |
-| **Initialize** | Automatic | `datalyr.init({...})` |
-| **Track Event** | `window.datalyr.track(...)` | `datalyr.track(...)` |
-| **Identify** | `window.datalyr.identify(...)` | `datalyr.identify(...)` |
-| **Get Visitor ID** | `window.datalyr.getVisitorId()` | `datalyr.getAnonymousId()` |
-| **Get Session** | `window.datalyr._getSessionId()` | `datalyr.getSessionId()` |
-| **Check Loaded** | `window.datalyr._isLoaded` | `datalyr.getAnonymousId() !== undefined` |
-
-Both methods use the same tracking backend and provide identical attribution tracking.
-
-## Browser Support
-
-The SDK supports all modern browsers:
-- Chrome/Edge 90+
-- Firefox 88+
-- Safari 14+
-- Opera 76+
-
-For older browsers, the SDK will gracefully degrade with fallback implementations.
+### Script tag vs NPM
 
-## Performance
+Choose one installation method. Using both causes conflicts.
 
-- **Bundle Size**: ~15KB minified + gzipped
-- **Zero Dependencies**: No external dependencies
-- **Optimized**: Smart event batching reduces network requests
-- **Fast**: Deferred loading for non-critical operations
-- **Memory Management**: Automatic cleanup of resources
+| Feature | Script Tag | NPM |
+|---------|-----------|-----|
+| Bundle Size | 0 (external) | ~15KB |
+| TypeScript | No | Yes |
+| Access | `window.datalyr` | `import datalyr` |
+| Initialize | Automatic | `datalyr.init()` |
 
-## Privacy & Compliance
-
-The SDK is designed with privacy in mind:
-
-- **GDPR Compliant**: Built-in consent management
-- **CCPA Support**: "Do Not Sell" preference support
-- **Cookie Control**: Configurable cookie settings
-- **Data Minimization**: Collect only what you need
-- **User Rights**: Easy opt-out and data deletion
-
-## Debugging
-
-Enable debug mode for detailed logging:
-
-```javascript
-import datalyr from '@datalyr/web';
-
-datalyr.init({
-  workspaceId: 'YOUR_WORKSPACE_ID',
-  debug: true
-});
-
-// Check console for detailed logs:
-// [Datalyr] SDK initialized
-// [Datalyr] Event tracked: Button Clicked
-// [Datalyr] Batch sent successfully: 5 events
-```
-
-## API Reference
-
-### Initialization Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `workspaceId` | `string` | *required* | Your Datalyr workspace ID |
-| `endpoint` | `string` | Default API | Custom endpoint URL |
-| `debug` | `boolean` | `false` | Enable debug logging |
-| `batchSize` | `number` | `10` | Number of events per batch |
-| `flushInterval` | `number` | `5000` | Time between flushes (ms) |
-| `sessionTimeout` | `number` | `1800000` | Session timeout (ms) |
-| `privacyMode` | `'standard' \| 'strict'` | `'standard'` | Privacy level |
-| `respectDoNotTrack` | `boolean` | `false` | Honor browser DNT |
-| `respectGlobalPrivacyControl` | `boolean` | `true` | Honor GPC |
-| `cookieDomain` | `string \| 'auto'` | `'auto'` | Cookie domain |
-| `trackSPA` | `boolean` | `true` | Track SPA routes |
-| `trackPageViews` | `boolean` | `true` | Track page views |
-| `enableContainer` | `boolean` | `true` | Enable secure container script loading |
-
-### Methods
-
-| Method | Description |
-|--------|-------------|
-| `init(config)` | Initialize the SDK with configuration |
-| `track(event, properties?)` | Track an event |
-| `identify(userId?, traits?)` | Identify a user |
-| `page(name?, properties?)` | Track a page view |
-| `alias(userId)` | Create an alias |
-| `reset()` | Reset identity |
-| `optOut()` | Opt out of tracking |
-| `optIn()` | Opt back in |
-| `setConsent(config)` | Set consent preferences |
-| `flush()` | Force send events |
-| `getAnonymousId()` | Get anonymous ID |
-| `getUserId()` | Get user ID |
-| `getDistinctId()` | Get distinct ID |
-| `getSessionId()` | Get session ID |
-| `getSessionData()` | Get session data |
-| `getErrors()` | Get SDK errors |
-| `loadScript(scriptId)` | Manually trigger a container script |
-| `getLoadedScripts()` | Get list of loaded container scripts |
-| `destroy()` | Clean up resources |
-
-## Support
-
-- **Documentation**: [https://docs.datalyr.com](https://docs.datalyr.com)
-- **Issues**: [GitHub Issues](https://github.com/datalyr/web/issues)
-- **Email**: support@datalyr.com
+---
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
-
----
-
-Built by the Datalyr team
+MIT