@breadstone/ziegel-platform-analytics

Analytics and tracking infrastructure for the ziegel platform. Provides analytics managers, multiple analytics providers (Google Analytics, etc.), data sanitization, and tracking utilities for enterprise applications.

Analytics: Enterprise analytics with multiple providers, data sanitization, and comprehensive tracking capabilities.

🚀 Overview

@breadstone/ziegel-platform-analytics provides:

• Analytics Manager: Centralized analytics tracking and management
• Multiple Providers: Support for Google Analytics, custom providers, and callback-based tracking
• Data Sanitization: Configurable data sanitization and privacy protection
• Provider Architecture: Extensible provider system for different analytics services
• Console Analytics: Development and debugging analytics provider
• Type Safety: Strongly typed analytics events and configurations

📦 Installation

npm install @breadstone/ziegel-platform-analytics
# or
yarn add @breadstone/ziegel-platform-analytics

🧩 Features & Usage Examples

Analytics Manager

import { AnalyticsManager, IAnalyticsManager } from '@breadstone/ziegel-platform-analytics';

// Create analytics manager
const analytics: IAnalyticsManager = new AnalyticsManager();

// Track events
analytics.trackEvent('user_action', {
  action: 'button_click',
  buttonId: 'save-profile',
  userId: '12345'
});

// Track page views
analytics.trackPageView('/dashboard', {
  referrer: document.referrer,
  userAgent: navigator.userAgent
});

Multiple Analytics Providers

import {
  GoogleAnalyticsProvider,
  ConsoleAnalyticsProvider,
  CallbackAnalyticsProvider
} from '@breadstone/ziegel-platform-analytics';

// Google Analytics integration
const googleProvider = new GoogleAnalyticsProvider({
  trackingId: 'GA_TRACKING_ID',
  cookieDomain: 'auto'
});

// Console provider for development
const consoleProvider = new ConsoleAnalyticsProvider({
  enableDebugLogging: true
});

// Custom callback provider
const callbackProvider = new CallbackAnalyticsProvider({
  onEvent: (eventName, properties) => {
    // Send to custom analytics endpoint
    fetch('/api/analytics', {
      method: 'POST',
      body: JSON.stringify({ eventName, properties })
    });
  }
});

// Register providers with analytics manager
analytics.addProvider(googleProvider);
analytics.addProvider(consoleProvider);
analytics.addProvider(callbackProvider);

Data Sanitization

import {
  AnalyticsSanitizer,
  IAnalyticsSanitizer,
  SanitizerKind
} from '@breadstone/ziegel-platform-analytics';

// Configure data sanitization
const sanitizer: IAnalyticsSanitizer = new AnalyticsSanitizer({
  enableSanitization: true,
  sanitizerKind: SanitizerKind.GDPR_COMPLIANT,
  removePersonalData: true,
  hashUserIds: true
});

// Apply sanitization to events
const rawEvent = {
  userId: 'user@example.com',
  action: 'purchase',
  email: 'user@example.com',
  amount: 99.99
};

const sanitizedEvent = sanitizer.sanitize(rawEvent);
// Results in: { userId: 'hashed_value', action: 'purchase', amount: 99.99 }

Custom Analytics Provider

import { AnalyticsProviderBase, IAnalyticsProvider } from '@breadstone/ziegel-platform-analytics';

class CustomAnalyticsProvider extends AnalyticsProviderBase implements IAnalyticsProvider {
  constructor(private config: CustomConfig) {
    super();
  }

  async initialize(): Promise<void> {
    // Initialize your analytics service
  }

  async trackEvent(eventName: string, properties: Record<string, any>): Promise<void> {
    // Send event to your analytics service
    await this.httpClient.post('/analytics/events', {
      name: eventName,
      properties,
      timestamp: Date.now()
    });
  }

  async trackPageView(page: string, properties?: Record<string, any>): Promise<void> {
    // Track page view in your analytics service
    await this.trackEvent('page_view', { page, ...properties });
  }
}

Callback-based Analytics

import { CallbackAnalyticsProvider, AnalyticCallback } from '@breadstone/ziegel-platform-analytics';

// Define callback for analytics events
const analyticsCallback: AnalyticCallback = (eventName, properties) => {
  console.log(`Analytics Event: ${eventName}`, properties);

  // Send to multiple endpoints
  Promise.all([
    fetch('/api/internal-analytics', {
      method: 'POST',
      body: JSON.stringify({ event: eventName, data: properties })
    }),
    fetch('/api/external-analytics', {
      method: 'POST',
      body: JSON.stringify({ eventName, properties })
    })
  ]);
};

const callbackProvider = new CallbackAnalyticsProvider({
  callback: analyticsCallback
});

📚 Package Exports

import {
    // Analytics Manager
    AnalyticsManager, IAnalyticsManager,

    // Analytics Providers
    AnalyticsProviderBase, IAnalyticsProvider, IAnalyticsProviderConfig,
    CallbackAnalyticsProvider, ConsoleAnalyticsProvider,
    GoogleAnalyticsProvider,

    // Callbacks & Types
    AnalyticCallback,

    // Data Sanitization
    AnalyticsSanitizerBase, AnalyticsSanitizer, IAnalyticsSanitizer,
    IAnalyticsSanitizerConfig, SanitizerKind
} from '@breadstone/ziegel-platform-analytics';

🛡️ Privacy & GDPR Compliance

Sanitization Strategies

import { SanitizerKind } from '@breadstone/ziegel-platform-analytics';

// Different sanitization levels
const gdprSanitizer = new AnalyticsSanitizer({
  sanitizerKind: SanitizerKind.GDPR_COMPLIANT,
  removePersonalData: true,
  hashUserIds: true,
  anonymizeIpAddresses: true
});

const basicSanitizer = new AnalyticsSanitizer({
  sanitizerKind: SanitizerKind.BASIC,
  removePersonalData: false,
  hashUserIds: false
});

// Apply sanitization before tracking
const sanitizedData = sanitizer.sanitize({
  userId: 'user@example.com',
  action: 'purchase',
  personalNote: 'This is private',
  amount: 99.99
});

Provider Configuration for Privacy

import { IAnalyticsProviderConfig } from '@breadstone/ziegel-platform-analytics';

const privacyCompliantConfig: IAnalyticsProviderConfig = {
  enableDataSanitization: true,
  respectDoNotTrack: true,
  enableConsentManagement: true,
  dataRetentionDays: 365,
  enableAnonymization: true
};

const provider = new GoogleAnalyticsProvider(privacyCompliantConfig);

🔧 Advanced Usage

Multi-Provider Setup

import { AnalyticsManager } from '@breadstone/ziegel-platform-analytics';

const analytics = new AnalyticsManager();

// Add multiple providers for redundancy
analytics.addProvider(new GoogleAnalyticsProvider({ trackingId: 'GA_ID' }));
analytics.addProvider(new CallbackAnalyticsProvider({
  callback: (event, props) => sendToDataWarehouse(event, props)
}));
analytics.addProvider(new ConsoleAnalyticsProvider({ enableDebugLogging: true }));

// Events will be sent to all registered providers
analytics.trackEvent('user_conversion', {
  conversionType: 'signup',
  source: 'organic',
  value: 100
});

Custom Sanitizer Implementation

import { AnalyticsSanitizerBase } from '@breadstone/ziegel-platform-analytics';

class CustomSanitizer extends AnalyticsSanitizerBase {
  sanitize(data: Record<string, any>): Record<string, any> {
    const sanitized = { ...data };

    // Remove email addresses
    if (sanitized.email) {
      sanitized.email = this.hashValue(sanitized.email);
    }

    // Truncate long text fields
    Object.keys(sanitized).forEach(key => {
      if (typeof sanitized[key] === 'string' && sanitized[key].length > 100) {
        sanitized[key] = sanitized[key].substring(0, 100) + '...';
      }
    });

    return sanitized;
  }

  private hashValue(value: string): string {
    // Implement your hashing logic
    return btoa(value).substring(0, 10);
  }
}

const customSanitizer = new CustomSanitizer();
analytics.setSanitizer(customSanitizer);

📊 Integration Examples

React Integration

import React, { useEffect } from 'react';
import { AnalyticsManager } from '@breadstone/ziegel-platform-analytics';

const analytics = new AnalyticsManager();

function ProductPage({ productId }: { productId: string }) {
  useEffect(() => {
    analytics.trackPageView(`/product/${productId}`, {
      productId,
      category: 'product-detail'
    });
  }, [productId]);

  const handleAddToCart = () => {
    analytics.trackEvent('add_to_cart', {
      productId,
      source: 'product_page',
      timestamp: Date.now()
    });
  };

  return (
    <div&gt;
      <button onClick={handleAddToCart}>Add to Cart</button&gt;
    </div&gt;
  );
}

E-commerce Tracking

// Track purchase funnel
analytics.trackEvent('product_view', { productId: 'ABC123' });
analytics.trackEvent('add_to_cart', { productId: 'ABC123', quantity: 1 });
analytics.trackEvent('checkout_start', { cartValue: 99.99 });
analytics.trackEvent('purchase_complete', {
  transactionId: 'TXN456',
  revenue: 99.99,
  products: ['ABC123']
});

📚 API Documentation

For detailed API documentation, visit: API Docs

Related Packages

• @breadstone/ziegel-platform: Core platform services
• @breadstone/ziegel-platform-logging: Logging infrastructure
• @breadstone/ziegel-core: Foundation utilities

License

MIT

Issues

Please report bugs and feature requests in the Issue Tracker

---

Part of the ziegel Enterprise TypeScript Framework

Related Packages

• ziegel-platform - Core platform services
• ziegel-platform-logging - Logging infrastructure