Web Behavior Tracker

A framework-agnostic npm package for tracking user behavior on web forms. This package helps you gather insights about how users interact with your forms, detect suspicious patterns, and calculate risk scores.

Features

• Track user interactions with form fields (focus, blur, input, change)
• Track copy-paste operations (copy, paste, cut events with clipboard data)
• Track custom events with rich data for business intelligence
• Monitor mouse movements and clicks
• Calculate risk scores based on user behavior
• Detect suspicious patterns (rapid form filling, copy-paste behavior, etc.)
• Generate detailed metrics and insights
• Framework-agnostic implementation
• TypeScript support
• Cross-page session tracking
• Automatic session persistence
• Configurable time-based risk thresholds
• Modular architecture with separate event handlers
• Browser metadata collection for device fingerprinting

Installation

npm install web-behavior-tracker

Quick Start

import { BehaviorTracker } from 'web-behavior-tracker';

// Create a new tracker instance
const tracker = new BehaviorTracker({
  trackMouseMovements: true,
  trackFocusBlur: true,
  trackInputChanges: true,
  trackClicks: true,
  trackCopyPaste: true,
  riskThreshold: 0.7,
  minTimeSpent: 10000,    // 10 seconds minimum
  maxTimeSpent: 600000,   // 10 minutes maximum
  throttleDelay: 150      // 150ms throttle delay
});

// Start tracking
tracker.startTracking();

// Get insights
const insights = tracker.getInsights();
console.log('Risk score:', insights.riskScore);
console.log('Suspicious patterns:', insights.suspiciousPatterns);

Architecture

The package uses a modular architecture with separate event handlers for better maintainability:

src/
├── BehaviorTracker.ts          # Main behavior tracking class
├── BrowserMetadataCollector.ts # Browser metadata collection
├── InputEventHandler.ts        # Input, delete, and autocomplete events
├── FormEventHandler.ts         # Form-specific events (select, submit, etc.)
├── MouseEventHandler.ts        # Mouse events (click, focus, blur, etc.)
├── ClipboardEventHandler.ts    # Clipboard events (copy, paste, cut)
├── CustomEventHandler.ts       # Custom events (user-defined events)
├── utils.ts                    # Shared utility functions
├── types.ts                    # TypeScript type definitions
└── index.ts                    # Main exports

Usage Patterns

1. Behavior Tracking Only

import { BehaviorTracker } from './src/BehaviorTracker.js';

const tracker = new BehaviorTracker();
tracker.startTracking();
const insights = tracker.getInsights();

2. Browser Metadata Only

import { BrowserMetadataCollector } from './src/BrowserMetadataCollector.js';

const metadata = BrowserMetadataCollector.getBrowserMetadata();
const fingerprint = BrowserMetadataCollector.getBrowserFingerprint();

3. Individual Event Handlers

import { InputEventHandler, FormEventHandler } from './src/index.js';

const inputHandler = new InputEventHandler({ trackInputChanges: true });
const formHandler = new FormEventHandler({ trackInputChanges: true });

Copy-Paste Tracking

Features

• Explicit Event Tracking: Captures copy, paste, and cut events on form elements
• Clipboard Data: Records clipboard content and data types when available
• Element Context: Tracks which form field the operation occurred on
• Timestamps: Records when each operation happened
• Fallback Detection: Uses rapid input events as indicators of copy-paste behavior

Usage

// Copy-paste tracking is enabled by default
const tracker = new BehaviorTracker({
  trackCopyPaste: true  // This is the default
});

// Get copy-paste metrics
const metrics = tracker.getMetrics();
console.log('Copy operations:', metrics.copyCount);
console.log('Paste operations:', metrics.pasteCount);
console.log('Cut operations:', metrics.cutCount);

// Get all events including copy-paste events
const events = tracker.getEvents();
const copyPasteEvents = events.filter(e => ['copy', 'paste', 'cut'].includes(e.type));

Event Data Structure

interface ClipboardData {
  types: string[];  // Available clipboard data types (e.g., ['text/plain'])
  data: string;     // The actual clipboard content
}

Custom Events

Track custom user actions and business events with rich data:

Basic Usage

// Track a simple custom event
tracker.trackCustomEvent('user_action', { action: 'button_clicked' });

// Track with target element
tracker.trackCustomEvent('form_error', { field: 'email' }, document.getElementById('email'));

// Track complex business events
tracker.trackCustomEvent('conversion', {
  type: 'purchase',
  value: 150.00,
  productIds: ['123', '456'],
  customerId: 'user_789'
});

Advanced Custom Event Examples

// Track user journey events
tracker.trackCustomEvent('page_navigation', {
  from: '/home',
  to: '/products',
  method: 'click',
  element: 'navigation-link'
});

// Track business metrics
tracker.trackCustomEvent('conversion', {
  type: 'purchase',
  value: 150.00,
  currency: 'USD',
  productIds: ['123', '456'],
  customerId: 'user_789'
});

// Track user behavior patterns
tracker.trackCustomEvent('scroll_behavior', {
  scrollDepth: 0.75,
  scrollDirection: 'down',
  timeOnPage: 45000,
  elementInView: 'product-gallery'
});

Custom Event Methods

• trackCustomEvent(eventName, customData, target?) - Creates and logs a custom event
• getCustomEvents() - Gets all custom events
• getCustomEventsByName(eventName) - Gets custom events by name
• getCustomEventsCount() - Gets total custom event count
• getCustomEventStats() - Gets detailed custom event statistics
• hasCustomEvent(eventName) - Checks if event has been triggered
• getLastCustomEvent(eventName?) - Gets last occurrence of event
• clearCustomEvents() - Clears all custom events

Custom Event Statistics

const stats = tracker.getCustomEventStats();
console.log(stats);
// Output:
// {
//   totalCustomEvents: 15,
//   eventsByName: {
//     'user_action': 5,
//     'conversion': 2,
//     'error': 3,
//     'engagement': 5
//   },
//   recentEvents: [...], // Last 10 events
//   lastEvent: {...} // Most recent event
// }

Browser Metadata Collection

The BrowserMetadataCollector provides comprehensive browser and device information:

Basic Browser Information

• userAgent: Full user agent string
• platform: Operating system platform (using modern User-Agent Client Hints API)
• platformVersion: Platform version (when available)
• browserName: Browser name (Chrome, Firefox, Safari, Edge)
• browserVersion: Browser version (when available)
• isMobile: Whether the device is mobile
• language: User's preferred language
• languages: Array of preferred languages
• cookieEnabled: Whether cookies are enabled
• onLine: Whether browser is online
• hardwareConcurrency: Number of CPU cores
• maxTouchPoints: Maximum touch points supported

Screen & Display Information

• screenWidth/Height: Screen dimensions
• screenAvailWidth/Height: Available screen dimensions
• screenColorDepth: Color depth
• screenPixelDepth: Pixel depth
• viewportWidth/Height: Browser viewport dimensions
• devicePixelRatio: Device pixel ratio

Usage

import { BrowserMetadataCollector } from 'web-behavior-tracker';

// Get basic metadata
const metadata = BrowserMetadataCollector.getBrowserMetadata();
console.log('Platform:', metadata.platform);
console.log('Browser:', metadata.browserName);
console.log('Is Mobile:', metadata.isMobile);

// Get browser fingerprint
const fingerprint = BrowserMetadataCollector.getBrowserFingerprint();
console.log('Fingerprint:', fingerprint);

// Get additional metadata (advanced system information)
const additionalMetadata = BrowserMetadataCollector.getAdditionalMetadata();

// Get high-entropy metadata (requires user permission)
const highEntropyMetadata = await BrowserMetadataCollector.getHighEntropyMetadata();

Cross-Page Tracking

The package automatically maintains a session across page navigations using the browser's sessionStorage:

• User behavior is tracked across all pages in the same session
• Data persists even when the user navigates between pages
• Each session has a unique ID that can be used to correlate events
• Session data is automatically saved when the user leaves a page
• Session data is cleared when the browser tab is closed

Session Management

// Start tracking without clearing existing session data
tracker.startTracking();

// Start tracking and clear all previous session data
tracker.startTracking(true);

// Get the current session ID
const sessionId = tracker.getSessionId();

// Clear the current session data
tracker.clearSession();

Configuration Options

interface TrackingOptions {
  trackMouseMovements?: boolean;  // Track mouse movements (default: false)
  trackFocusBlur?: boolean;       // Track focus and blur events (default: true)
  trackInputChanges?: boolean;    // Track input and change events (default: true)
  trackClicks?: boolean;          // Track click events (default: true)
  trackCopyPaste?: boolean;       // Track copy-paste operations (default: true)
  customEvents?: string[];        // Additional events to track
  riskThreshold?: number;         // Threshold for risk score (default: 0.7)
  minTimeSpent?: number;          // Minimum time in milliseconds before considering it suspicious (default: 5000ms)
  maxTimeSpent?: number;          // Maximum time in milliseconds before considering it suspicious (default: 300000ms)
  throttleDelay?: number;         // Throttle delay in milliseconds to prevent excessive event tracking (default: 100ms)
}

Time-Based Risk Assessment

The package uses time-based thresholds to assess risk:

• If a user spends less than minTimeSpent (default: 5 seconds) on the form, it increases the risk score by 0.3
• If a user spends more than maxTimeSpent (default: 5 minutes) on the form, it increases the risk score by 0.2

// Example: Custom time thresholds for a complex form
const tracker = new BehaviorTracker({
  minTimeSpent: 30000,    // 30 seconds minimum
  maxTimeSpent: 900000    // 15 minutes maximum
});

// Example: Stricter thresholds for a simple form
const tracker = new BehaviorTracker({
  minTimeSpent: 2000,     // 2 seconds minimum
  maxTimeSpent: 120000    // 2 minutes maximum
});

Event Throttling

Events are throttled based on the throttleDelay parameter (default: 100ms) to prevent excessive event tracking:

// More aggressive throttling for high-frequency events
const tracker = new BehaviorTracker({
  throttleDelay: 200      // 200ms throttle delay
});

// Less throttling for more detailed tracking
const tracker = new BehaviorTracker({
  throttleDelay: 50       // 50ms throttle delay
});

Metrics

The package provides comprehensive metrics:

• Time spent on the form
• Number of field interactions
• Number of field changes
• Focus and blur counts
• Mouse interaction counts
• Copy, paste, and cut operation counts
• Cross-page navigation patterns
• Page-specific interaction data
• Custom event counts and statistics

Insights

The insights include:

• Risk score (0-1)
• Suspicious patterns detected
• Form completion rate
• Average time per field
• Field interaction order
• Cross-page behavior patterns
• Session-level risk assessment
• Custom event statistics
• Browser metadata and capabilities

Use Cases

Fraud Detection

• Detect unusual browser configurations
• Identify automated browsers
• Track device fingerprinting
• Monitor suspicious behavior patterns

User Experience

• Optimize for different screen sizes
• Adapt to user's language preferences
• Monitor performance metrics
• Track user journey and engagement

Analytics

• Understand user demographics
• Track device capabilities
• Monitor browser usage patterns
• Business intelligence and conversion tracking

A/B Testing

• Variant selection tracking
• Test completion rates
• User behavior differences
• Conversion impact analysis

Privacy Considerations

• Some metadata requires user permission (geolocation, battery, media devices)
• Be mindful of privacy regulations (GDPR, CCPA)
• Consider anonymizing sensitive data
• Only collect necessary information

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT