@shadowoff09/web-analytics

A lightweight, privacy-focused web analytics package for tracking user interactions on your website.

Installation

npm install @shadowoff09/web-analytics
# or
yarn add @shadowoff09/web-analytics

Usage

import Analytics from '@shadowoff09/web-analytics';

// Initialize the analytics
const analytics = new Analytics({
  endpoint: 'https://your-analytics-api.com',
  siteId: 'your-site-id',
  debug: true // Optional: enables console logging
});

// Set user ID (optional)
analytics.setUserId('user123');

// Track custom events
analytics.trackEvent('button_click', {
  buttonId: 'signup',
  location: 'header'
});

// Page views are tracked automatically

Features

• Automatic page view tracking
• Custom event tracking
• Session management
• User identification
• Browser and OS detection
• SPA navigation support
• Beacon API support with fetch fallback
• TypeScript support
• Debug mode

API Reference

Configuration

interface AnalyticsConfig {
  endpoint: string;    // Your analytics API endpoint
  siteId: string;     // Your site identifier
  debug?: boolean;    // Enable debug logging (default: false)
}

Methods

setUserId(userId: string)

Set the current user's ID for tracking purposes.

trackPageView()

Manually track a page view (called automatically on initialization and navigation).

trackEvent(eventName: string, properties: EventProperties)

Track a custom event with optional properties.

License

MIT