portfolio/ANALYTICS.md

# Analytics & Performance Tracking System

## Übersicht

Dieses Portfolio verwendet ein **GDPR-konformes Analytics-System** basierend auf **Umami** (self-hosted) mit erweitertem **Performance-Tracking**.

## Features

### ✅ GDPR-Konform
- **Keine Cookie-Banner** erforderlich
- **Keine personenbezogenen Daten** werden gesammelt
- **Anonymisierte Performance-Metriken**
- **Self-hosted** - vollständige Datenkontrolle

### 📊 Analytics Features
- **Page Views** - Seitenaufrufe
- **User Interactions** - Klicks, Formulare, Scroll-Verhalten
- **Error Tracking** - JavaScript-Fehler und unhandled rejections
- **Route Changes** - SPA-Navigation

### ⚡ Performance Tracking
- **Core Web Vitals**: LCP, FID, CLS, FCP, TTFB
- **Page Load Times** - Detaillierte Timing-Phasen
- **API Response Times** - Backend-Performance
- **Custom Performance Markers** - Spezifische Metriken

## Technische Implementierung

### 1. Umami Integration
```typescript
// Bereits in layout.tsx konfiguriert
<script
  defer
  src="https://umami.denshooter.de/script.js"
  data-website-id="1f213877-deef-4238-8df1-71a5a3bcd142"
></script>
```

### 2. Performance Tracking
```typescript
// Web Vitals werden automatisch getrackt
import { useWebVitals } from '@/lib/useWebVitals';

// Custom Events tracken
import { trackEvent, trackPerformance } from '@/lib/analytics';

trackEvent('custom-action', { data: 'value' });
trackPerformance({ name: 'api-call', value: 150, url: '/api/data' });
```

### 3. Analytics Provider
```typescript
// Automatisches Tracking von:
// - Page Views
// - User Interactions (Klicks, Scroll, Forms)
// - Performance Metrics
// - Error Tracking
<AnalyticsProvider>
  {children}
</AnalyticsProvider>
```

## Dashboard

### Performance Dashboard
- **Live Performance-Metriken** anzeigen
- **Core Web Vitals** mit Bewertungen (Good/Needs Improvement/Poor)
- **Toggle-Button** unten rechts auf der Website
- **Real-time Updates** der Performance-Daten

### Umami Dashboard
- **Standard Analytics** über deine Umami-Instanz
- **URL**: https://umami.denshooter.de
- **Website ID**: 1f213877-deef-4238-8df1-71a5a3bcd142

## Event-Typen

### Automatische Events
- `page-view` - Seitenaufrufe
- `click` - Benutzerklicks
- `form-submit` - Formular-Übermittlungen
- `scroll-depth` - Scroll-Tiefe (25%, 50%, 75%, 90%)
- `error` - JavaScript-Fehler
- `unhandled-rejection` - Unbehandelte Promise-Rejections

### Performance Events
- `web-vitals` - Core Web Vitals (LCP, FID, CLS, FCP, TTFB)
- `performance` - Custom Performance-Metriken
- `page-timing` - Detaillierte Page-Load-Phasen
- `api-call` - API-Response-Zeiten

### Custom Events
- `dashboard-toggle` - Performance Dashboard ein/aus
- `interaction` - Benutzerinteraktionen

## Datenschutz

### Was wird NICHT gesammelt:
- ❌ IP-Adressen
- ❌ User-IDs
- ❌ E-Mail-Adressen
- ❌ Personenbezogene Daten
- ❌ Cookies

### Was wird gesammelt:
- ✅ Anonymisierte Performance-Metriken
- ✅ Technische Browser-Informationen
- ✅ Seitenaufrufe (ohne persönliche Daten)
- ✅ Error-Logs (anonymisiert)

## Konfiguration

### Umami Setup
1. **Self-hosted Umami** auf deinem Server
2. **Website ID** in `layout.tsx` konfiguriert
3. **Script-URL** auf deine Umami-Instanz

### Performance Tracking
- **Automatisch aktiviert** durch `AnalyticsProvider`
- **Web Vitals** werden automatisch gemessen
- **Custom Events** über `trackEvent()` Funktion

## Monitoring

### Performance-Schwellenwerte
- **LCP**: ≤ 2.5s (Good), ≤ 4s (Needs Improvement), > 4s (Poor)
- **FID**: ≤ 100ms (Good), ≤ 300ms (Needs Improvement), > 300ms (Poor)
- **CLS**: ≤ 0.1 (Good), ≤ 0.25 (Needs Improvement), > 0.25 (Poor)
- **FCP**: ≤ 1.8s (Good), ≤ 3s (Needs Improvement), > 3s (Poor)
- **TTFB**: ≤ 800ms (Good), ≤ 1.8s (Needs Improvement), > 1.8s (Poor)

### Dashboard-Zugriff
- **Performance Dashboard**: Toggle-Button unten rechts
- **Umami Dashboard**: https://umami.denshooter.de
- **API Endpoint**: `/api/analytics` für Custom-Tracking

## Erweiterung

### Neue Events hinzufügen
```typescript
import { trackEvent } from '@/lib/analytics';

// Custom Event tracken
trackEvent('feature-usage', {
  feature: 'contact-form',
  success: true,
  duration: 1500
});
```

### Performance-Metriken erweitern
```typescript
import { trackPerformance } from '@/lib/analytics';

// Custom Performance-Metrik
trackPerformance({
  name: 'component-render',
  value: renderTime,
  url: window.location.pathname
});
```

## Troubleshooting

### Performance Dashboard nicht sichtbar
- Prüfe Browser-Konsole auf Fehler
- Stelle sicher, dass `AnalyticsProvider` in `layout.tsx` eingebunden ist

### Umami Events nicht sichtbar
- Prüfe Umami-Dashboard auf https://umami.denshooter.de
- Stelle sicher, dass Website ID korrekt ist
- Prüfe Browser-Netzwerk-Tab auf Umami-Requests

### Performance-Metriken fehlen
- Prüfe Browser-Konsole auf Performance Observer Fehler
- Stelle sicher, dass `useWebVitals` Hook aktiv ist
- Teste in verschiedenen Browsern