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.

✨ 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

npm install isometrik-web-tracker

🚀 Quick Start

Basic Usage

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

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

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.

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

untrackElement(trackingKey)

Stop tracking an element.

tracker.untrackElement('hero');

getTrackingData()

Get complete tracking data.

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

getFormattedData()

Get human-readable formatted data.

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

getActivityStats()

Get activity statistics.

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

getElementTrackingData(trackingKey)

Get data for a specific element.

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

pause()

Pause all tracking.

tracker.pause();

resume()

Resume tracking.

tracker.resume();

reset()

Reset all tracking data.

tracker.reset();

exportData()

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

const exported = tracker.exportData();

destroy()

Clean up and destroy the tracker.

tracker.destroy();

🎯 Individual Tracking Modules

ActivityDetector

Detect general user activity across all interaction types.

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.

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.

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.

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.

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.

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.

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

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

NetworkTracker

Track network connectivity.

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

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

📊 Data Types

TimeTrackingData

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

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

ActivityStats

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

🔧 Advanced Examples

E-commerce Analytics

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

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

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

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:

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

// 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

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

2. Use Appropriate Thresholds

// 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

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

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 file for details.

🆘 Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

🔄 Changelog

v1.0.0

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

Made with ❤️ by the Isometrik team