michaelschiemer/docs/modules/analytics.md

# Analytics Module

**Unified Analytics System for Event Tracking and User Behavior**

The Analytics Module provides a comprehensive analytics system with GDPR compliance and multiple provider support.

---

## Features

- **Event Tracking** - Track custom events
- **Page View Tracking** - Automatic and manual page view tracking
- **User Behavior Tracking** - Track user interactions
- **Multiple Providers** - Support for Google Analytics, custom endpoints, and more
- **GDPR Compliance** - Consent management and data anonymization
- **Integration with LiveComponents** - Automatic tracking of LiveComponent events
- **User Identification** - Identify users for user-level analytics

---

## Quick Start

### Basic Usage

```javascript
import { Analytics } from './modules/analytics/index.js';

// Create analytics instance
const analytics = Analytics.create({
    providers: ['google-analytics'],
    gdprCompliant: true,
    requireConsent: true
});

// Give consent (GDPR)
analytics.giveConsent();

// Track event
await analytics.track('button_click', {
    button_id: 'submit',
    page: '/contact'
});

// Track page view
await analytics.trackPageView('/dashboard');
```

### Module System Integration

```html
<!-- Enable global analytics -->
<script type="module">
    import { init } from './modules/analytics/index.js';
    
    init({
        providers: [
            {
                type: 'google-analytics',
                measurementId: 'G-XXXXXXXXXX'
            },
            {
                type: 'custom',
                endpoint: '/api/analytics'
            }
        ],
        gdprCompliant: true,
        requireConsent: true
    });
</script>

<!-- Access globally -->
<script>
    // Give consent
    window.Analytics.giveConsent();
    
    // Track event
    window.Analytics.track('purchase', {
        value: 99.99,
        currency: 'EUR'
    });
</script>
```

---

## API Reference

### Analytics.create(config)

Create a new Analytics instance.

**Parameters**:
- `config.enabled` - Enable analytics (default: true)
- `config.providers` - Array of provider configs
- `config.gdprCompliant` - Enable GDPR compliance (default: true)
- `config.requireConsent` - Require user consent (default: false)
- `config.anonymizeIp` - Anonymize IP addresses (default: true)

### analytics.track(eventName, properties)

Track a custom event.

**Parameters**:
- `eventName` - Event name
- `properties` - Event properties

**Example**:
```javascript
await analytics.track('purchase', {
    value: 99.99,
    currency: 'EUR',
    items: [{ id: 'product-1', quantity: 1 }]
});
```

### analytics.trackPageView(path, properties)

Track a page view.

**Parameters**:
- `path` - Page path (optional, defaults to current path)
- `properties` - Additional properties

### analytics.identify(userId, traits)

Identify a user.

**Parameters**:
- `userId` - User ID
- `traits` - User traits (name, email, etc.)

**Example**:
```javascript
await analytics.identify('user-123', {
    name: 'John Doe',
    email: 'john@example.com'
});
```

### analytics.trackBehavior(action, target, properties)

Track user behavior.

**Parameters**:
- `action` - Action type (click, scroll, etc.)
- `target` - Target element or identifier
- `properties` - Additional properties

### analytics.giveConsent()

Give GDPR consent.

### analytics.revokeConsent()

Revoke GDPR consent.

---

## Providers

### Google Analytics

```javascript
const analytics = Analytics.create({
    providers: [
        {
            type: 'google-analytics',
            measurementId: 'G-XXXXXXXXXX'
        }
    ]
});
```

### Custom Provider

```javascript
const analytics = Analytics.create({
    providers: [
        {
            type: 'custom',
            endpoint: '/api/analytics'
        }
    ]
});
```

### Multiple Providers

```javascript
const analytics = Analytics.create({
    providers: [
        'google-analytics',
        {
            type: 'custom',
            endpoint: '/api/analytics'
        }
    ]
});
```

---

## GDPR Compliance

### Consent Management

```javascript
const analytics = Analytics.create({
    requireConsent: true,
    gdprCompliant: true
});

// Show consent banner
showConsentBanner(() => {
    analytics.giveConsent();
});
```

### Data Anonymization

```javascript
// IP addresses are automatically anonymized
// PII fields are automatically removed
await analytics.track('event', {
    email: 'user@example.com', // Will be removed
    ip: '192.168.1.1' // Will be anonymized to 192.168.1.0
});
```

---

## Integration with LiveComponents

```javascript
import { Analytics } from './modules/analytics/index.js';
import { LiveComponent } from './modules/livecomponent/index.js';

const analytics = Analytics.create();

// Track LiveComponent actions
LiveComponent.on('action-executed', (componentId, actionName, params) => {
    analytics.track('livecomponent:action', {
        component_id: componentId,
        action: actionName,
        params
    });
});

// Track component updates
LiveComponent.on('component-updated', (componentId) => {
    analytics.track('livecomponent:updated', {
        component_id: componentId
    });
});
```

---

## Use Cases

### E-commerce Tracking

```javascript
// Track purchase
await analytics.track('purchase', {
    value: 99.99,
    currency: 'EUR',
    items: [
        { id: 'product-1', name: 'Product 1', price: 49.99, quantity: 1 },
        { id: 'product-2', name: 'Product 2', price: 50.00, quantity: 1 }
    ]
});

// Track add to cart
await analytics.track('add_to_cart', {
    product_id: 'product-1',
    value: 49.99
});
```

### User Behavior Tracking

```javascript
// Track button clicks
document.addEventListener('click', (event) => {
    if (event.target.matches('[data-track]')) {
        analytics.trackBehavior('click', event.target.id, {
            text: event.target.textContent
        });
    }
});

// Track form submissions
document.addEventListener('submit', (event) => {
    analytics.track('form_submit', {
        form_id: event.target.id,
        form_name: event.target.name
    });
});
```

### Page View Tracking

```javascript
// Automatic tracking on navigation
// Or manual tracking
await analytics.trackPageView('/dashboard', {
    section: 'admin',
    user_role: 'admin'
});
```

---

## Best Practices

1. **Respect User Privacy** - Always get consent before tracking
2. **Anonymize Data** - Remove PII and anonymize IPs
3. **Track Meaningful Events** - Focus on business-critical events
4. **Use Consistent Naming** - Use consistent event names
5. **Monitor Performance** - Don't let analytics slow down the app

---

## Browser Support

- **Chrome/Edge**: 90+
- **Firefox**: 88+
- **Safari**: 14+
- **Mobile**: iOS 14+, Android Chrome 90+

**Required Features**:
- ES2020 JavaScript
- Fetch API
- CustomEvent support

---

**Next**: Continue with remaining modules →