🎯 scrubbe-auth Analytics

✨ Features

• 🔒 Privacy-First - GDPR compliant with built-in consent management
• 🎯 Device Fingerprinting - Advanced browser and device identification
• 📍 Location Tracking - GPS and IP-based geolocation with privacy controls
• 🌐 Network Analysis - Connection type, speed, and ISP detection
• 👤 User Behavior - Page views, clicks, scrolling, and session tracking
• 🚀 High Performance - Optimized batching and minimal overhead
• 🔧 Modular Architecture - Use only what you need
• 📊 Real-time Analytics - Live data streaming and processing
• 🛡️ Enterprise Ready - Scalable, secure, and production-tested

📦 Packages

| Package | Version | Description | |---------|---------|-------------| | @scrubbe-auth/analytics | | Core analytics engine | | @scrubbe-auth/device-fingerprint | | Advanced device fingerprinting | | @scrubbe-auth/location-tracker | | Location and IP tracking | | @scrubbe-auth/network-info | | Network information detection | | @scrubbe-auth/user-tracker | | User activity and behavior tracking |

🚀 Quick Start

Installation

# Install core package
npm install @scrubbe-auth/analytics

# Or install all modules
npm install @scrubbe-auth/analytics @scrubbe-auth/device-fingerprint @scrubbe-auth/location-tracker @scrubbe-auth/network-info @scrubbe-auth/user-tracker



## Basic Usage
```import { Analytics } from '@scrubbe-auth/analytics';

 Initialize with minimal configuration
const analytics = new Analytics({
  projectId: 'your-project-id',
  apiKey: 'your-api-key'
});

 Start tracking
   await analytics.init();

Track events
  analytics.track('button_click', {
  buttonId: 'cta-signup',
  page: '/landing'
}); ```


## Advanced Setup
``` import { Analytics } from '@scrubbe-auth/analytics';
import { DeviceFingerprint } from '@scrubbe-auth/device-fingerprint';
import { LocationTracker } from '@scrubbe-auth/location-tracker';

const analytics = new Analytics({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  autoTrack: true,
  privacy: {
    respectDNT: true,
    anonymizeIP: true
  }
});

// Add advanced tracking modules
const deviceFP = new DeviceFingerprint({
  enableCanvas: true,
  enableWebGL: true
});

const locationTracker = new LocationTracker({
  enableGPS: false, // Requires user permission
  enableIP: true
});

// Integrate modules
analytics.use(deviceFP);
analytics.use(locationTracker);

// Start comprehensive tracking
await analytics.start(); ```



## 📊 Usage Examples

### Event Tracking

```// Page views
analytics.page('/dashboard', {
  category: 'app',
  userId: 'user_123'
});

// Custom events
analytics.track('purchase_completed', {
  orderId: 'order_456',
  revenue: 99.99,
  currency: 'USD'
});

// User identification
analytics.identify('user_123', {
  email: '[email protected]',
  plan: 'premium'
}); ```


### Device Fingerprinting

``` import { DeviceFingerprint } from '@scrubbe-auth/device-fingerprint';

const deviceFP = new DeviceFingerprint({
  enableCanvas: true,
  enableWebGL: true,
  enableAudio: false // Disable for better performance
});

const fingerprint = await deviceFP.generate();
console.log('Unique Device ID:', fingerprint.deviceId);
console.log('Confidence Score:', fingerprint.confidence); ```


### Location Tracking 
``` import { LocationTracker } from '@scrubbe-auth/location-tracker';

const locationTracker = new LocationTracker({
  enableGPS: true,
  accuracy: 'high'
});

const location = await locationTracker.getLocation();
console.log('Location:', location.city, location.country);  ```



## ⚙️ Configuration

### Environment Variables

# Required
scrubbe-auth_PROJECT_ID=your-project-id
scrubbe-auth_API_KEY=your-api-key

# Optional
scrubbe-auth_ENVIRONMENT=production
scrubbe-auth_DEBUG=false
scrubbe-auth_BATCH_SIZE=100



### Privacy Settings

``` const analytics = new Analytics({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  privacy: {
    respectDNT: true,        // Honor Do Not Track
    anonymizeIP: true,       // Anonymize IP addresses
    consentRequired: true,   // Require explicit consent
    cookieConsent: true      // Cookie consent integration
  }
});   ```


### Performance Optimization

``` const analytics = new Analytics({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  batchSize: 100,           // Events per batch
  flushInterval: 5000,      // Flush every 5 seconds
  transport: {
    compression: true,      // Enable data compression
    retries: 3             // Retry failed requests
  }
});  ```


### 🔧 Development
### Prerequisites
      - Node.js ≥ 18.0.0

      - pnpm ≥ 8.0.0


## 📝 API Reference
###  Core Analytics

``` interface Analytics {
  // Initialization
  init(): Promise<void>;
  start(): Promise<void>;
  stop(): void;

  // Event tracking
  track(event: string, properties?: Record<string, any>): void;
  page(page: string, properties?: Record<string, any>): void;
  identify(userId: string, traits?: Record<string, any>): void;
  alias(newId: string, previousId?: string): void;

  // Module integration
  use(module: AnalyticsModule): void;

  // Event listeners
  on(event: string, callback: Function): void;
  off(event: string, callback: Function): void;
} ```


### Device Fingerprinting

``` interface DeviceFingerprint {
  generate(): Promise<FingerprintResult>;
  clearCache(): void;
  getConfig(): DeviceFingerprintConfig;
}

interface FingerprintResult {
  deviceId: string;
  confidence: number;
  canvas?: CanvasFingerprint;
  webgl?: WebGLFingerprint;
  audio?: AudioFingerprint;
  screen?: ScreenFingerprint;
  browser?: BrowserFingerprint;
}```



## 🛡️ Privacy & Security

  - GDPR Compliant - Built-in privacy controls and consent management

  - Data Minimization - Collect only necessary data

  - Encryption - End-to-end data encryption

  - Anonymization - IP address and PII anonymization

  - Consent Management - Granular privacy controls

  - Do Not Track - Automatic DNT header respect


  ### 🔍 Troubleshooting

  Common Issues 

  Module not found errors

  ``` # Clear cache and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install  ```

## Build failures

``` # Clean and rebuild
pnpm clean
pnpm build   ```

# TypeScript errors

``` # Check TypeScript configuration
pnpm typecheck ```


# Debug Mode
```  const analytics = new Analytics({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  debug: true // Enable debug logging
});   ```