isometrik-web-tracker/README.md

Production-grade user tracking library with multiple tracking methods

# Isometrik Web Tracker 🎯

A comprehensive, production-grade user tracking library for web applications. Track user behavior, element visibility, engagement metrics, and more with zero performance impact.

[![npm version](https://badge.fury.io/js/isometrik-web-tracker.svg)](https://badge.fury.io/js/isometrik-web-tracker)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-4.9+-blue.svg)](https://www.typescriptlang.org/)

## ✨ Features

- 🎯 **Element Visibility Tracking** - Track when elements enter/exit viewport
- 🖱️ **Mouse Activity** - Clicks, movements, hovers, drags
- ⌨️ **Keyboard Interactions** - Keystrokes, key combinations
- 📜 **Scroll Behavior** - Depth, velocity, direction tracking
- 👆 **Touch Gestures** - Tap, swipe, pinch, long press
- 👁️ **Focus & Visibility** - Window focus, page visibility
- 🌐 **Network Status** - Online/offline monitoring
- ⏱️ **Time Tracking** - Active time, idle time, engagement rates
- 🔒 **Privacy-First** - GDPR compliant, secure data handling
- 🚀 **Performance Optimized** - Zero impact on page performance
- 📱 **Mobile Ready** - Touch and gesture support
- 🔧 **TypeScript** - Full type safety and IntelliSense

## 📦 Installation

```bash
npm install isometrik-web-tracker
```

## 🚀 Quick Start

### Basic Usage

```typescript
import PageTimeTracker from 'isometrik-web-tracker';

// Initialize the tracker
const tracker = new PageTimeTracker({
  enableConsoleLog: true, // Enable for development
  onTimeUpdate: data => {
    console.log('Time update:', data);
  },
  onElementVisible: (elementKey, data) => {
    console.log('Element visible:', elementKey, data);
  },
});

// Track specific elements
tracker.trackElement('#hero-section', 'hero', {
  trackVisibility: true,
  trackInteractions: true,
  threshold: 0.5, // 50% visible
});

tracker.trackElement('#signup-form', 'signup', {
  trackVisibility: true,
  trackInteractions: true,
  threshold: 0.3, // 30% visible
});

// Get tracking data
const data = tracker.getTrackingData();
console.log('Tracking data:', data);
```

### Advanced Usage

```typescript
import PageTimeTracker from 'isometrik-web-tracker';

const tracker = new PageTimeTracker({
  idleThreshold: 30000, // 30 seconds
  trackingInterval: 1000, // 1 second updates
  enableConsoleLog: false, // Disable in production
  secureModeEnabled: true, // Encrypt data
  trackingKey: 'my-app-v1',

  // Callbacks
  onActivityChange: (isActive, activityType) => {
    console.log('Activity changed:', isActive, activityType);
  },

  onTimeUpdate: data => {
    // Send to analytics service
    analytics.track('page_time', {
      sessionId: data.sessionId,
      totalTime: data.totalTimeSpent,
      activeTime: data.activeTimeSpent,
      engagementRate: (data.activeTimeSpent / data.totalTimeSpent) * 100,
    });
  },

  onElementVisible: (elementKey, data) => {
    analytics.track('element_visible', {
      elementKey,
      visibleTime: data.totalVisibleTime,
      visibilityCount: data.visibilityCount,
    });
  },

  onTrackingEvent: event => {
    // Send encrypted data to your server
    fetch('/api/tracking', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ event: btoa(JSON.stringify(event)) }),
    });
  },
});
```

## 📚 API Reference

### PageTimeTracker

The main class that orchestrates all tracking functionality.

#### Constructor Options

```typescript
interface TrackerOptions {
  idleThreshold?: number; // milliseconds (default: 30000)
  trackingInterval?: number; // milliseconds (default: 1000)
  enableConsoleLog?: boolean; // default: false
  secureModeEnabled?: boolean; // default: false
  trackingKey?: string; // auto-generated if not provided

  // Callbacks
  onActivityChange?: (isActive: boolean, activityType?: ActivityType) => void;
  onTimeUpdate?: (data: TimeTrackingData) => void;
  onElementVisible?: (elementKey: string, data: ElementTrackingData) => void;
  onElementHidden?: (elementKey: string, data: ElementTrackingData) => void;
  onTrackingEvent?: (event: TrackingEvent) => void;
}
```

#### Methods

##### `trackElement(element, trackingKey, options?)`

Track an element for visibility and interactions.

```typescript
tracker.trackElement('#hero-section', 'hero', {
  trackVisibility: true,
  trackInteractions: true,
  threshold: 0.5, // 50% visible
});
```

##### `untrackElement(trackingKey)`

Stop tracking an element.

```typescript
tracker.untrackElement('hero');
```

##### `getTrackingData()`

Get complete tracking data.

```typescript
const data = tracker.getTrackingData();
// Returns TimeTrackingData object
```

##### `getFormattedData()`

Get human-readable formatted data.

```typescript
const formatted = tracker.getFormattedData();
// Returns: { totalTime: "2m 30s", activeTime: "1m 45s", ... }
```

##### `getActivityStats()`

Get activity statistics.

```typescript
const stats = tracker.getActivityStats();
// Returns: { mouseEvents: 45, keyboardEvents: 12, ... }
```

##### `getElementTrackingData(trackingKey)`

Get data for a specific element.

```typescript
const elementData = tracker.getElementTrackingData('hero');
```

##### `pause()`

Pause all tracking.

```typescript
tracker.pause();
```

##### `resume()`

Resume tracking.

```typescript
tracker.resume();
```

##### `reset()`

Reset all tracking data.

```typescript
tracker.reset();
```

##### `exportData()`

Export data as JSON string (encrypted if secure mode enabled).

```typescript
const exported = tracker.exportData();
```

##### `destroy()`

Clean up and destroy the tracker.

```typescript
tracker.destroy();
```

## 🎯 Individual Tracking Modules

### ActivityDetector

Detect general user activity across all interaction types.

```typescript
import { ActivityDetector } from 'isometrik-web-tracker';

const detector = new ActivityDetector({
  enableConsoleLog: true,
  onActivity: activityType => {
    console.log('Activity detected:', activityType);
  },
});
```

### ElementVisibilityTracker

Track element visibility using IntersectionObserver.

```typescript
import { ElementVisibilityTracker } from 'isometrik-web-tracker';

const visibilityTracker = new ElementVisibilityTracker({
  enableConsoleLog: true,
  onVisible: (elementKey, element, data) => {
    console.log('Element became visible:', elementKey, data);
  },
  onHidden: (elementKey, element, data) => {
    console.log('Element became hidden:', elementKey, data);
  },
});

// Track an element
visibilityTracker.trackElement(document.querySelector('#hero'), 'hero', {
  threshold: 0.5, // 50% visible
});
```

### MouseTracker

Track mouse interactions.

```typescript
import { MouseTracker } from 'isometrik-web-tracker';

const mouseTracker = new MouseTracker({
  enableConsoleLog: true,
  trackClicks: true,
  trackMovement: true,
  trackHovers: true,
  onMouseActivity: data => {
    console.log('Mouse activity:', data);
  },
});
```

### ScrollTracker

Track scrolling behavior.

```typescript
import { ScrollTracker } from 'isometrik-web-tracker';

const scrollTracker = new ScrollTracker({
  enableConsoleLog: true,
  trackDepth: true,
  trackVelocity: true,
  onScrollActivity: data => {
    console.log('Scroll activity:', data);
  },
});

// Get current scroll depth
const depth = scrollTracker.getCurrentScrollDepth(); // 0-100%
```

### KeyboardTracker

Track keyboard interactions.

```typescript
import { KeyboardTracker } from 'isometrik-web-tracker';

const keyboardTracker = new KeyboardTracker({
  enableConsoleLog: true,
  trackKeystrokes: true,
  trackCombinations: true,
  onKeyboardActivity: data => {
    console.log('Keyboard activity:', data);
  },
});
```

### TouchTracker

Track touch gestures on mobile devices.

```typescript
import { TouchTracker } from 'isometrik-web-tracker';

const touchTracker = new TouchTracker({
  enableConsoleLog: true,
  trackGestures: true,
  trackPressure: true,
  onTouchActivity: data => {
    console.log('Touch activity:', data);
  },
});
```

### FocusTracker

Track window focus and page visibility.

```typescript
import { FocusTracker } from 'isometrik-web-tracker';

const focusTracker = new FocusTracker({
  enableConsoleLog: true,
  onFocusChange: hasFocus => {
    console.log('Focus changed:', hasFocus);
  },
});
```

### NetworkTracker

Track network connectivity.

```typescript
import { NetworkTracker } from 'isometrik-web-tracker';

const networkTracker = new NetworkTracker({
  enableConsoleLog: true,
  onNetworkChange: isOnline => {
    console.log('Network status:', isOnline);
  },
});
```

## 📊 Data Types

### TimeTrackingData

```typescript
interface TimeTrackingData {
  sessionId: string;
  trackingKey: string;
  totalTimeSpent: number;
  activeTimeSpent: number;
  idleTimeSpent: number;
  pageVisits: number;
  lastActivity: Date;
  sessionStart: Date;
  url: string;
  title: string;
  referrer: string;
  userAgent: string;
  elementTrackingData: Record<string, ElementTrackingData>;
  activityHistory: TrackingEvent[];
}
```

### ElementTrackingData

```typescript
interface ElementTrackingData {
  elementKey: string;
  totalVisibleTime: number;
  visibilityCount: number;
  firstSeen: Date;
  lastSeen: Date;
  isCurrentlyVisible: boolean;
  viewportPercentage: number;
  interactions: ElementInteraction[];
}
```

### ActivityStats

```typescript
interface ActivityStats {
  mouseEvents: number;
  keyboardEvents: number;
  scrollEvents: number;
  touchEvents: number;
  totalEvents: number;
}
```

## 🔧 Advanced Examples

### E-commerce Analytics

```typescript
const tracker = new PageTimeTracker({
  onElementVisible: (elementKey, data) => {
    if (elementKey === 'product-card') {
      analytics.track('product_view', {
        productId: data.elementKey,
        viewTime: data.totalVisibleTime,
        interactions: data.interactions.length,
      });
    }
  },

  onTrackingEvent: event => {
    if (event.type === 'element_interaction' && event.data.type === 'click') {
      analytics.track('product_click', {
        productId: event.data.elementKey,
        position: event.data.position,
      });
    }
  },
});

// Track product cards
document.querySelectorAll('.product-card').forEach((card, index) => {
  tracker.trackElement(card, `product-${index}`, {
    trackVisibility: true,
    trackInteractions: true,
    threshold: 0.3,
  });
});
```

### Form Analytics

```typescript
const tracker = new PageTimeTracker({
  onElementVisible: (elementKey, data) => {
    if (elementKey.startsWith('form-field-')) {
      analytics.track('form_field_view', {
        fieldName: elementKey,
        viewTime: data.totalVisibleTime,
      });
    }
  },
});

// Track form fields
document.querySelectorAll('input, textarea, select').forEach(field => {
  const fieldName = field.name || field.id || 'unknown';
  tracker.trackElement(field, `form-field-${fieldName}`, {
    trackVisibility: true,
    trackInteractions: true,
  });
});
```

### Content Engagement

```typescript
const tracker = new PageTimeTracker({
  onTimeUpdate: data => {
    const engagementRate = (data.activeTimeSpent / data.totalTimeSpent) * 100;

    if (engagementRate > 70) {
      analytics.track('high_engagement', {
        sessionId: data.sessionId,
        engagementRate,
        totalTime: data.totalTimeSpent,
      });
    }
  },
});

// Track content sections
document.querySelectorAll('section, article').forEach((section, index) => {
  tracker.trackElement(section, `content-${index}`, {
    trackVisibility: true,
    trackInteractions: true,
    threshold: 0.5,
  });
});
```

### Performance Monitoring

```typescript
const tracker = new PageTimeTracker({
  onTrackingEvent: event => {
    // Monitor for performance issues
    if (event.type === 'scroll' && event.data.velocity > 1000) {
      console.warn('High scroll velocity detected');
    }

    if (event.type === 'mouse' && event.data.movement) {
      const distance = Math.sqrt(
        event.data.movement.x ** 2 + event.data.movement.y ** 2
      );
      if (distance > 100) {
        console.warn('Large mouse movement detected');
      }
    }
  },
});
```

## 🔒 Privacy & Security

### GDPR Compliance

The library is designed with privacy in mind:

- **No Personal Data**: Only tracks interaction patterns, not personal information
- **User Consent**: Respects user privacy preferences
- **Data Minimization**: Only collects necessary data
- **Transparency**: Clear data collection practices

### Secure Mode

Enable secure mode to encrypt all tracking data:

```typescript
const tracker = new PageTimeTracker({
  secureModeEnabled: true, // Encrypt all data
  enableConsoleLog: false, // Disable console logs
  onTrackingEvent: event => {
    // Send encrypted data to your server
    fetch('/api/tracking', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ event: btoa(JSON.stringify(event)) }),
    });
  },
});
```

### Privacy Controls

```typescript
// Pause tracking when user opts out
function pauseTracking() {
  tracker.pause();
  localStorage.setItem('tracking-consent', 'false');
}

// Resume tracking when user consents
function resumeTracking() {
  tracker.resume();
  localStorage.setItem('tracking-consent', 'true');
}

// Check user consent
if (localStorage.getItem('tracking-consent') === 'false') {
  tracker.pause();
}
```

## 🚀 Performance Optimization

### Best Practices

1. **Disable Console Logs in Production**

```typescript
const tracker = new PageTimeTracker({
  enableConsoleLog: process.env.NODE_ENV === 'development',
});
```

2. **Use Appropriate Thresholds**

```typescript
// For important elements (CTAs, forms)
tracker.trackElement('#cta-button', 'cta', { threshold: 0.1 });

// For content sections
tracker.trackElement('#content', 'content', { threshold: 0.5 });
```

3. **Clean Up on Page Unload**

```typescript
window.addEventListener('beforeunload', () => {
  const finalData = tracker.getTrackingData();
  // Send final data to server
  navigator.sendBeacon('/api/tracking/end', JSON.stringify(finalData));
  tracker.destroy();
});
```

4. **Batch Data Sending**

```typescript
let eventBuffer = [];

const tracker = new PageTimeTracker({
  onTrackingEvent: event => {
    eventBuffer.push(event);

    if (eventBuffer.length >= 10) {
      // Send batch of events
      fetch('/api/tracking/batch', {
        method: 'POST',
        body: JSON.stringify(eventBuffer),
      });
      eventBuffer = [];
    }
  },
});
```

## 🌐 Browser Support

- **Chrome**: 60+
- **Firefox**: 55+
- **Safari**: 12+
- **Edge**: 79+
- **Mobile Safari**: 12+
- **Chrome Mobile**: 60+

## 📦 Bundle Size

- **Minified**: ~45KB
- **Gzipped**: ~15KB
- **Tree-shakeable**: Import only what you need

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🆘 Support

- **Documentation**: [GitHub Wiki](https://github.com/yourusername/isometrik-web-tracker/wiki)
- **Issues**: [GitHub Issues](https://github.com/yourusername/isometrik-web-tracker/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/isometrik-web-tracker/discussions)

## 🔄 Changelog

### v1.0.0

- Initial release
- Complete tracking functionality
- TypeScript support
- Performance optimizations
- Privacy features

---

**Made with ❤️ by the Isometrik team**