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

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

<!-- 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:

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:

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

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

Custom Provider

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

Multiple Providers

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

---

GDPR Compliance

Consent Management

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

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

Data Anonymization

// 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

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

// 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

// 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

// 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 →