user-analytics-tracker 1.2.0 → 2.0.0

package/CHANGELOG.md

@@ -1,3 +1,72 @@
+# [2.0.0](https://github.com/switch-org/analytics-tracker/compare/v1.7.0...v2.0.0) (2025-12-01)
+
+
+### Features
+
+* major improvements - event batching, retry logic, plugins, and more ([f47b0ea](https://github.com/switch-org/analytics-tracker/commit/f47b0ea0f7bde575d4d91a2ae807fb074065c55c))
+* major improvements - event batching, retry logic, plugins, and more ([46d0c1c](https://github.com/switch-org/analytics-tracker/commit/46d0c1c3e8435dec70fb04e99ad0902198c1486c))
+
+
+### BREAKING CHANGES
+
+* None - all changes are backward compatible
+* None - all changes are backward compatible
+
+# [1.8.0](https://github.com/switch-org/analytics-tracker/compare/v1.7.0...v1.8.0) (2025-01-XX)
+
+### Features
+
+* **Event Batching & Queue System**: Automatic event batching reduces API calls by 50-90%. Events are queued and sent in configurable batches (default: 10 events per batch, 5 second intervals)
+* **Offline Support**: Events are persisted to localStorage and automatically sent when connection is restored
+* **Retry Logic with Exponential Backoff**: Automatic retry mechanism for failed requests with exponential backoff (1s, 2s, 4s, 8s). Configurable max retries (default: 3)
+* **Enhanced Logging System**: Configurable log levels (`silent`, `error`, `warn`, `info`, `debug`) with automatic dev/prod level selection
+* **Plugin/Middleware System**: Extensible plugin architecture for event transformation, filtering, and enrichment. Supports `beforeSend`, `afterSend`, and `onError` hooks
+* **Session Management Improvements**: Enhanced session tracking with timeout detection (default: 30 min), automatic session renewal, and session utilities
+* **Developer Debugging Tools**: Built-in debug utilities accessible via `window.__analyticsDebug` in development mode. Includes queue inspection, manual flush, and stats
+* **Performance Monitoring & Metrics**: Optional metrics collection tracking events sent/queued/failed, average send time, retry counts, and error history
+* **Enhanced Configuration Options**: New config options for batching (`batchSize`, `batchInterval`, `maxQueueSize`), retry (`maxRetries`, `retryDelay`), session (`sessionTimeout`), logging (`logLevel`), and metrics (`enableMetrics`)
+
+### Improvements
+
+* Better error handling with graceful degradation
+* Improved test coverage for new features
+* Enhanced TypeScript types for all new features
+
+# [1.7.0](https://github.com/switch-org/analytics-tracker/compare/v1.6.0...v1.7.0) (2025-11-24)
+
+
+### Features
+
+* updated build ([4778be5](https://github.com/switch-org/analytics-tracker/commit/4778be5c9f41a034593c02a97c70076c480dd1ed))
+
+# [1.6.0](https://github.com/switch-org/analytics-tracker/compare/v1.5.0...v1.6.0) (2025-11-24)
+
+
+### Features
+
+* update permissions ([553d9be](https://github.com/switch-org/analytics-tracker/commit/553d9be405d7609e2cb9853ff16535cf4b1b9e66))
+
+# [1.5.0](https://github.com/switch-org/analytics-tracker/compare/v1.4.0...v1.5.0) (2025-11-24)
+
+
+### Features
+
+* updated ([a5d770b](https://github.com/switch-org/analytics-tracker/commit/a5d770b97719707c458601f955a98655c1baa27f))
+
+# [1.4.0](https://github.com/switch-org/analytics-tracker/compare/v1.3.1...v1.4.0) (2025-11-24)
+
+
+### Features
+
+* updated doc ([9d606f4](https://github.com/switch-org/analytics-tracker/commit/9d606f4a735dcc7b0aeda30615328b5bda54c4bc))
+
+## [1.3.1](https://github.com/switch-org/analytics-tracker/compare/v1.3.0...v1.3.1) (2025-11-24)
+
+
+### Bug Fixes
+
+* updated names ([c56f903](https://github.com/switch-org/analytics-tracker/commit/c56f903b9360f2dc2492e5114667dc240cca9e0c))
+
 # [1.3.0](https://github.com/switch-org/analytics-tracker/compare/v1.2.0...v1.3.0) (2025-11-24)
 
 

package/README.md

@@ -13,13 +13,22 @@ A comprehensive, lightweight analytics tracking library for React applications.
 - 🔍 **Device Detection**: Automatically detects device type, OS, browser, model, brand, and hardware specs using User-Agent Client Hints
 - 🌐 **Network Detection**: Identifies WiFi, Cellular, Hotspot, Ethernet connections with quality metrics
 - 📍 **Location Tracking**: 
-  - **Automatic IP-based location** (no permission required) - works immediately
-  - GPS location with consent management (MSISDN-based consent)
+  - **IP-based location** - Requires user consent (privacy-compliant)
+  - **GPS location** - Requires explicit user consent and browser permission
   - Includes public IP address, country, city, region, timezone
   - Automatic fallback from GPS to IP when GPS unavailable
+  - Consent management utilities included
 - 🎯 **Attribution Tracking**: UTM parameters, referrer tracking, first/last touch attribution
 - 📊 **IP Geolocation**: Client-side and server-side IP-based location detection utilities
-- 🔒 **Privacy-First**: Location consent management, automatic IP fallback
+- 🔒 **Privacy-First**: User consent required for location tracking (GPS & IP), consent management utilities
+- 🎯 **Custom Event Tracking**: Firebase/Google Analytics-style event tracking with automatic context collection
+- ⚡ **Event Batching & Queue System**: Automatic event batching reduces API calls by 50-90%. Events are queued and sent in configurable batches with offline persistence
+- 🔄 **Retry Logic**: Automatic retry with exponential backoff for failed requests. Configurable retry attempts and delays
+- 📝 **Enhanced Logging**: Configurable log levels (silent, error, warn, info, debug) with automatic dev/prod level selection
+- 🔌 **Plugin System**: Extensible plugin architecture for event transformation, filtering, and enrichment
+- 📈 **Session Management**: Enhanced session tracking with timeout detection and automatic renewal
+- 🐛 **Debug Tools**: Built-in debugging utilities for development (queue inspection, manual flush, stats)
+- 📊 **Performance Metrics**: Optional metrics collection for monitoring events, retries, and performance
 - ⚡ **Lightweight**: Zero runtime dependencies (except React)
 - 📦 **TypeScript**: Fully typed with comprehensive type definitions
 - 🎨 **Framework Agnostic Core**: Core detectors work without React
@@ -57,6 +66,36 @@ function App() {
 }
 ```
 
+### Advanced Configuration Options
+
+The package now supports extensive configuration options for batching, retry logic, logging, and more:
+
+```tsx
+const analytics = useAnalytics({
+  config: {
+    apiEndpoint: 'https://api.yourcompany.com/analytics',
+    
+    // Event batching configuration
+    batchSize: 10,              // Events per batch (default: 10)
+    batchInterval: 5000,        // Flush interval in ms (default: 5000)
+    maxQueueSize: 100,          // Max queued events (default: 100)
+    
+    // Retry configuration
+    maxRetries: 3,              // Max retry attempts (default: 3)
+    retryDelay: 1000,           // Initial retry delay in ms (default: 1000)
+    
+    // Session configuration
+    sessionTimeout: 1800000,    // Session timeout in ms (default: 30 min)
+    
+    // Logging configuration
+    logLevel: 'warn',           // 'silent' | 'error' | 'warn' | 'info' | 'debug' (default: 'warn')
+    
+    // Metrics configuration
+    enableMetrics: false,       // Enable metrics collection (default: false)
+  },
+});
+```
+
 ### Configuration Options
 
 You can configure your backend URL in three ways:
@@ -169,7 +208,14 @@ function App() {
 import { useAnalytics } from 'user-analytics-tracker';
 
 function MyApp() {
-  const { sessionId, networkInfo, deviceInfo, location, logEvent } = useAnalytics({
+  const { 
+    sessionId, 
+    networkInfo, 
+    deviceInfo, 
+    location, 
+    trackEvent, 
+    trackPageView 
+  } = useAnalytics({
     autoSend: true,
     config: {
       // Use your own backend server (full URL)
@@ -179,11 +225,24 @@ function MyApp() {
     },
   });
 
+  // Track page view on mount
+  useEffect(() => {
+    trackPageView();
+  }, [trackPageView]);
+
+  const handleButtonClick = async () => {
+    // Track custom event (Firebase/GA-style)
+    await trackEvent('button_click', {
+      button_name: 'signup',
+      button_location: 'header'
+    });
+  };
+
   return (
     <div>
       <p>Device: {deviceInfo?.deviceBrand} {deviceInfo?.deviceModel}</p>
       <p>Network: {networkInfo?.type}</p>
-      <button onClick={() => logEvent({ action: 'button_click' })}>
+      <button onClick={handleButtonClick}>
         Track Click
       </button>
     </div>
@@ -250,6 +309,32 @@ interface UseAnalyticsOptions {
     attribution: AttributionInfo;
   }) => void; // Callback when data is ready
 }
+
+interface AnalyticsConfig {
+  apiEndpoint: string;
+  // Batching options
+  batchSize?: number;        // Events per batch (default: 10)
+  batchInterval?: number;    // Flush interval in ms (default: 5000)
+  maxQueueSize?: number;     // Max queued events (default: 100)
+  // Retry options
+  maxRetries?: number;       // Max retry attempts (default: 3)
+  retryDelay?: number;       // Initial retry delay in ms (default: 1000)
+  // Session options
+  sessionTimeout?: number;   // Session timeout in ms (default: 1800000 = 30 min)
+  // Logging options
+  logLevel?: LogLevel;       // 'silent' | 'error' | 'warn' | 'info' | 'debug' (default: 'warn')
+  // Metrics options
+  enableMetrics?: boolean;   // Enable metrics collection (default: false)
+  // Existing options
+  autoSend?: boolean;
+  enableLocation?: boolean;
+  enableIPGeolocation?: boolean;
+  enableNetworkDetection?: boolean;
+  enableDeviceDetection?: boolean;
+  enableAttribution?: boolean;
+  sessionStoragePrefix?: string;
+  localStoragePrefix?: string;
+}
 ```
 
 #### Returns
@@ -264,6 +349,8 @@ interface UseAnalyticsReturn {
   pageVisits: number;
   interactions: number;
   logEvent: (customData?: Record<string, any>) => Promise<void>;
+  trackEvent: (eventName: string, parameters?: Record<string, any>) => Promise<void>;
+  trackPageView: (pageName?: string, parameters?: Record<string, any>) => Promise<void>;
   incrementInteraction: () => void;
   refresh: () => Promise<{
     net: NetworkInfo;
@@ -392,6 +479,26 @@ const attribution = AttributionDetector.detect();
 
 ### Services
 
+#### `AnalyticsService.configure()`
+
+Configure the analytics service with advanced options.
+
+```typescript
+import { AnalyticsService } from 'user-analytics-tracker';
+
+AnalyticsService.configure({
+  apiEndpoint: 'https://api.yourcompany.com/analytics',
+  batchSize: 20,              // Events per batch (default: 10)
+  batchInterval: 10000,       // Flush interval in ms (default: 5000)
+  maxQueueSize: 100,          // Max queued events (default: 100)
+  maxRetries: 5,              // Max retry attempts (default: 3)
+  retryDelay: 2000,           // Initial retry delay in ms (default: 1000)
+  sessionTimeout: 1800000,    // Session timeout in ms (default: 30 min)
+  logLevel: 'info',           // Logging verbosity (default: 'warn')
+  enableMetrics: true,        // Enable metrics collection (default: false)
+});
+```
+
 #### `AnalyticsService.trackUserJourney()`
 
 Send analytics data to your backend.
@@ -419,8 +526,111 @@ await AnalyticsService.trackUserJourney({
 });
 ```
 
+#### `AnalyticsService.flushQueue()`
+
+Manually flush the event queue (useful before page unload).
+
+```typescript
+// Flush all queued events immediately
+await AnalyticsService.flushQueue();
+```
+
+#### `AnalyticsService.getQueueSize()`
+
+Get the current number of events in the queue.
+
+```typescript
+const size = AnalyticsService.getQueueSize();
+console.log(`Queue has ${size} events`);
+```
+
+#### `AnalyticsService.getMetrics()`
+
+Get performance metrics (if enabled).
+
+```typescript
+const metrics = AnalyticsService.getMetrics();
+if (metrics) {
+  console.log(`Sent: ${metrics.eventsSent}, Failed: ${metrics.eventsFailed}`);
+}
+```
+
 ### Utilities
 
+#### Logger
+
+Configure logging levels for better debugging and production use.
+
+```typescript
+import { logger } from 'user-analytics-tracker';
+
+// Set log level
+logger.setLevel('debug'); // 'silent' | 'error' | 'warn' | 'info' | 'debug'
+
+// Use logger
+logger.debug('Debug message');
+logger.info('Info message');
+logger.warn('Warning message');
+logger.error('Error message');
+```
+
+#### Plugin Manager
+
+Register and manage plugins for event transformation.
+
+```typescript
+import { pluginManager } from 'user-analytics-tracker';
+
+// Register a plugin
+pluginManager.register({
+  name: 'my-plugin',
+  beforeSend: (event) => {
+    // Transform event
+    return event;
+  },
+});
+
+// Unregister a plugin
+pluginManager.unregister('my-plugin');
+
+// Get all plugins
+const plugins = pluginManager.getPlugins();
+```
+
+#### Queue Manager
+
+Advanced queue management (for power users).
+
+```typescript
+import { QueueManager } from 'user-analytics-tracker';
+
+const queue = new QueueManager({
+  batchSize: 20,
+  batchInterval: 10000,
+  maxQueueSize: 200,
+  storageKey: 'my-queue',
+});
+
+queue.setFlushCallback(async (events) => {
+  // Custom flush logic
+});
+```
+
+#### Metrics Collector
+
+Collect and monitor analytics performance metrics.
+
+```typescript
+import { metricsCollector } from 'user-analytics-tracker';
+
+// Metrics are automatically collected when enableMetrics is true
+// Access metrics
+const metrics = metricsCollector.getMetrics();
+
+// Reset metrics
+metricsCollector.reset();
+```
+
 #### Location Consent Management
 
 ```typescript
@@ -444,6 +654,45 @@ setLocationConsentGranted();
 clearLocationConsent();
 ```
 
+#### Session Management
+
+Enhanced session tracking utilities.
+
+```typescript
+import {
+  getOrCreateSession,
+  updateSessionActivity,
+  getSession,
+  clearSession,
+} from 'user-analytics-tracker';
+
+// Get or create session with custom timeout (30 minutes)
+const session = getOrCreateSession(30 * 60 * 1000);
+// Returns: { sessionId, startTime, lastActivity, pageViews }
+
+// Update session activity
+updateSessionActivity();
+
+// Get current session
+const currentSession = getSession();
+
+// Clear session
+clearSession();
+```
+
+#### Debug Utilities
+
+Development debugging tools.
+
+```typescript
+import { initDebug } from 'user-analytics-tracker';
+
+// Initialize debug tools (automatically called in development)
+initDebug();
+
+// Then access via window.__analyticsDebug in browser console
+```
+
 #### IP Geolocation Utilities
 
 **Client-Side: Get Public IP**
@@ -527,12 +776,46 @@ class MyAnalyticsService extends AnalyticsService {
 }
 ```
 
-### Manual Event Tracking
+### Custom Event Tracking (Firebase/GA-style)
+
+Track custom events with automatic context collection:
+
+```typescript
+const { trackEvent, trackPageView } = useAnalytics();
+
+// Track button click
+await trackEvent('button_click', {
+  button_name: 'signup',
+  button_location: 'header',
+  button_color: 'blue'
+});
+
+// Track purchase
+await trackEvent('purchase', {
+  transaction_id: 'T12345',
+  value: 29.99,
+  currency: 'USD',
+  items: [
+    { id: 'item1', name: 'Product 1', price: 29.99 }
+  ]
+});
+
+// Track page views
+await trackPageView('/dashboard', {
+  page_title: 'Dashboard',
+  user_type: 'premium'
+});
+
+// Track current page view
+await trackPageView();
+```
+
+### Manual Event Tracking (Legacy)
 
 ```typescript
 const { logEvent, incrementInteraction } = useAnalytics();
 
-// Log custom event
+// Log custom event with full control
 await logEvent({
   eventType: 'purchase',
   productId: '123',