# ANALYTICS IMPLEMENTATION - KOMPLETT-GUIDE

**AegisSight UG**
**Datum:** 2026-03-20
**Version:** 2.0
**Status:** Implementation Complete

---

# PHASE 1: BESTANDSAUFNAHME

## Dienste & Tracking Katalog

### **Dienste im Einsatz:**
- **AegisSight Analytics (Umami v3.0.3)** - Self-Hosted, Deutschland
- Keine Google Analytics
- Keine Facebook Pixel
- Keine Third-Party CDNs
- Keine Social Media Widgets

### **Cookies:**

**Keine.** Umami arbeitet vollständig cookieless. Es werden weder Session-Cookies noch Tracking-Cookies gesetzt. Die Identifikation erfolgt ohne Cookies und ohne Fingerprinting.

| Eintrag | Zweck | Typ | Opt-In? |
|---------|-------|-----|---------|
| `analytics-consent` (LocalStorage) | Consent-Status | LocalStorage | Nein (technisch) |

### **Tracking-Daten (anonymisiert):**
- Browser, OS, Device, Screen Resolution
- Land, Region (kein Stadtlevel, kein GeoIP-Lookup)
- Seiten, Referrer, Session-Dauer
- Traffic Source, UTM-Parameter

### **Personenbezug:** Nein

Umami speichert keine IP-Adressen und verwendet kein Fingerprinting. Alle Daten sind aggregiert und nicht auf einzelne Nutzer rückführbar.

**Rechtsgrundlage:** Art. 6 Abs. 1 lit. f DSGVO (berechtigtes Interesse) - da cookieless und ohne Personenbezug ist kein Opt-In zwingend erforderlich. Der Consent-Banner wird dennoch aus Transparenzgründen eingesetzt.

---

# PHASE 2: ENTSCHEIDUNG & DESIGN

## **Entscheidung: CUSTOM BANNER**

**Gründe:**
- Nur 1 Dienst - CMP wäre Overkill
- Volle Kontrolle, keine Abhängigkeiten
- Schneller (<5KB vs. 50-100KB für CMP)
- Kostenlos

---

## **UI-Design: Slim Layer**

### Banner (Primary):
```
┌─────────────────────────────────────────┐
│ Website-Analyse                         │
│                                         │
│ Text: Cookieless Analytics, Self-       │
│ Hosted in Deutschland, keine            │
│ Weitergabe an Dritte...                 │
│                                         │
│ [Details & Einstellungen]               │
│ [Alles akzeptieren] [Nur notwendige]    │
└─────────────────────────────────────────┘
```

### Settings Modal:
```
┌─────────────────────────────────────┐
│ Analyse-Einstellungen           [×] │
├─────────────────────────────────────┤
│ ☑ Notwendig (immer aktiv)           │
│ ☐ Statistik & Analyse              │
│   └─ AegisSight Analytics (Umami)  │
│      • Keine Cookies                │
│      • Keine IP-Speicherung         │
│      • Self-Hosted, Deutschland     │
│                                     │
│ [Auswahl speichern] [Alle akz.]    │
└─────────────────────────────────────┘
```

---

## **Texte (DE/EN)**

**Deutsch:**
- Titel: "Website-Analyse"
- Text: "Wir nutzen cookielose Analyse-Software auf unserem eigenen Server in Deutschland. Es werden keine persönlichen Daten gespeichert und nichts an Dritte weitergegeben."
- Buttons: "Alles akzeptieren" / "Nur notwendige"

**Englisch:**
- Title: "Website Analytics"
- Text: "We use cookieless analytics software on our own server in Germany. No personal data is stored and nothing is shared with third parties."
- Buttons: "Accept all" / "Only necessary"

---

# PHASE 3: IMPLEMENTATIONSPLAN

## **3.1 Gating-Pattern**

```
Page Load
    ↓
Check LocalStorage['analytics-consent']
    ↓
    ├─→ null       → Show Banner + Block Tracking
    ├─→ 'accepted' → Load Umami Script
    └─→ 'rejected' → Block Tracking
```

**Ablauf:** Das Umami-Script `/analytics-und-so/datenblick.js` wird erst nach Zustimmung geladen.

---

## **3.2 Script-Einbindung**

### Umami Tracking-Script (wird dynamisch geladen bei Consent):

```html
<script
  defer
  src="/analytics-und-so/datenblick.js"
  data-website-id="598ef5fd-d2dc-4540-9e65-602889981dac"
></script>
```

### API-Endpoint:
```
POST /analytics-und-so/api/erfassen
```

---

## **3.3 Storage-Schema**

### LocalStorage Keys:

```javascript
// Consent Status
"analytics-consent": {
  value: "accepted" | "rejected",
  expires: 1774051200000  // Timestamp (12 Monate)
}

// Consent Details (Audit-Trail)
"analytics-consent-details": {
  timestamp: "2026-03-20T12:00:00Z",
  version: "2.0",
  categories: { necessary: true, analytics: true },
  language: "de",
  gpcSignal: false
}
```

---

## **3.4 Footer-Link (Persistent)**

```html
<footer>
  <a href="#" id="cookie-settings-link">Analyse-Einstellungen</a>
</footer>
```

**Funktion:** Öffnet Banner erneut, ermöglicht Widerruf

---

## **3.5 Re-Prompt Regeln**

**Banner erneut zeigen bei:**
1. Consent abgelaufen (nach 12 Monaten)
2. Version-Change (z.B. 2.0 → 2.1)
3. User löscht LocalStorage
4. Klick auf "Analyse-Einstellungen"

---

## **3.6 Global Privacy Control (GPC)**

```javascript
if (navigator.globalPrivacyControl === true) {
  // Auto-reject analytics
  localStorage.setItem('analytics-consent', JSON.stringify({
    value: 'rejected',
    expires: Date.now() + 365 * 24 * 60 * 60 * 1000
  }));
}
```

---

# PHASE 4: UMSETZUNG + TESTS

## **4.1 Dateien**

### **1. cookie-consent.css**
- Responsive Design (Mobile-First)
- Accessibility (Focus-Trap, ARIA, Keyboard)
- Animations (Fade-In, Slide-Up)
- Dark Mode kompatibel

### **2. cookie-consent.js**
- Consent Management Logic
- GPC Detection
- LocalStorage mit Expiry
- Multilingual (DE/EN)
- Public API
- Version Control
- Dynamisches Laden von `/analytics-und-so/datenblick.js`

### **3. DATENSCHUTZ_ANALYTICS.md**
- Fertige Datenschutzerklärung
- DSGVO-konforme Texte

---

## **4.2 Features implementiert**

- **Opt-In vor Tracking** (Gating)
- **Backdrop-Overlay** (verhindert Interaktion)
- **Two-Step Design** (Banner → Settings)
- **Consent-Versionierung** (Re-Prompt bei Updates)
- **GPC/DNT Support** (Auto-Reject)
- **LocalStorage mit Expiry** (12 Monate)
- **Audit-Trail** (Consent-Details)
- **Multilingual** (DE/EN)
- **Accessibility** (ARIA, Focus-Trap, Keyboard)
- **Responsive** (Mobile-optimiert)
- **Public API** (programmatischer Zugriff)
- **Cookieless Tracking** (keine Cookies nötig)

---

## **4.3 Test-Checkliste**

### **Funktional:**
- [ ] Banner erscheint beim ersten Besuch
- [ ] "Alles akzeptieren" lädt `/analytics-und-so/datenblick.js`
- [ ] "Nur notwendige" blockiert Script-Laden
- [ ] Re-Visit: Kein Banner (Consent gespeichert)
- [ ] Footer-Link öffnet Banner erneut
- [ ] Widerruf funktioniert (Accept → Reject)
- [ ] GPC-Signal wird erkannt und respektiert
- [ ] Version-Change löst Re-Prompt aus

### **Script-Integration:**
- [ ] Script hat korrektes `data-website-id="598ef5fd-d2dc-4540-9e65-602889981dac"`
- [ ] Pageview wird an `/analytics-und-so/api/erfassen` gesendet
- [ ] Keine Cookies im Browser nach Tracking

### **Accessibility & Responsive:**
- [ ] Keyboard-Navigation funktioniert (Tab, Enter, Esc)
- [ ] Screen Reader liest Banner korrekt vor
- [ ] Mobile: Buttons sind touchbar, kein horizontaler Scroll

---

## **4.4 Browser-Kompatibilität**

| Browser | Version | Status |
|---------|---------|--------|
| Chrome | 120+ | - |
| Firefox | 121+ | - |
| Safari | 17+ | - |
| Edge | 120+ | - |
| Chrome Mobile | 120+ | - |
| Safari iOS | 17+ | - |

**Minimum Support:** ES6 (2015+), LocalStorage, Fetch API

---

# PHASE 5: DATENSCHUTZERKLÄRUNG

## **5.1 Textbausteine**

**Datei:** `DATENSCHUTZ_ANALYTICS.md`

**Enthält:**
- Art und Umfang der Datenverarbeitung
- Rechtsgrundlage (Art. 6 Abs. 1 lit. f DSGVO - berechtigtes Interesse)
- Hinweis auf cookieloses Tracking
- Keine IP-Speicherung, kein Fingerprinting
- Self-Hosted auf eigenem Server (Deutschland)
- Keine Datenübermittlung an Dritte
- Widerruf der Einwilligung
- GPC-Unterstützung
- Betroffenenrechte (Art. 15-21 DSGVO)

---

## **5.2 Integration in Website**

```html
<!-- /datenschutz.html -->
<section id="analytics">
  <h2>4. Website-Analyse</h2>
  <p>Wir nutzen AegisSight Analytics (Umami), eine cookielose, datenschutzfreundliche
  Analyse-Software. Diese wird auf unserem eigenen Server in Deutschland betrieben.
  Es werden keine Cookies gesetzt, keine IP-Adressen gespeichert und kein
  Fingerprinting eingesetzt. Die erhobenen Daten sind nicht auf einzelne Personen
  rückführbar.</p>
</section>
```

---

## **5.3 Rechtliche Checkliste**

- [x] Opt-In vor Tracking (Consent-Banner)
- [x] Widerruf ermöglichen (Footer-Link)
- [x] Datenschutzerklärung (vollständig)
- [x] Rechtsgrundlage benannt (Art. 6 I f DSGVO)
- [x] Hinweis cookieloses Tracking
- [x] Betroffenenrechte (Art. 15-21)
- [ ] Impressum vollständig (muss geprüft werden)
- [ ] Aufsichtsbehörde (muss eingefügt werden)

---

# DEPLOYMENT-ANLEITUNG

## **1. Dateien auf Server**

```
/var/www/html/
├── cookie-consent.css
├── cookie-consent.js
└── cookie-consent-demo.html (optional)
```

## **2. Umami-Infrastruktur**

```
Analytics-System: Umami v3.0.3 (Node.js/Next.js)
Datenbank:        PostgreSQL
Script-Pfad:      /analytics-und-so/datenblick.js
API-Endpoint:     /analytics-und-so/api/erfassen
Website-ID:       598ef5fd-d2dc-4540-9e65-602889981dac
```

---

## **3. In HTML-Seiten integrieren**

```html
<!DOCTYPE html>
<html lang="de">
<head>
    <meta charset="UTF-8">
    <title>Ihre Seite</title>
    <link rel="stylesheet" href="/cookie-consent.css">
</head>
<body>
    <!-- Inhalt -->

    <footer>
        <nav>
            <a href="/datenschutz">Datenschutz</a>
            <a href="/impressum">Impressum</a>
            <a href="#" id="cookie-settings-link">Analyse-Einstellungen</a>
        </nav>
    </footer>

    <!-- Cookie Consent MUSS VOR allem anderen JS geladen werden -->
    <script src="/cookie-consent.js"></script>

    <!-- Umami-Script wird automatisch bei Consent geladen -->
    <!-- NICHT direkt einbinden! -->
</body>
</html>
```

---

## **4. Container neu laden**

```bash
docker exec aegis-website-nginx nginx -s reload
```

---

# WARTUNG & UPDATES

## **Vierteljährlich:**
- [ ] Umami-Version prüfen und ggf. updaten
- [ ] Datenschutzerklärung überprüfen

## **Jährlich:**
- [ ] Rechtsgrundlagen aktualisieren
- [ ] Consent-Version erhöhen (bei Änderungen)

---

# TROUBLESHOOTING

## **Problem: Banner erscheint nicht**

```javascript
// In Browser-Console:
localStorage.removeItem('analytics-consent');
localStorage.removeItem('analytics-consent-details');
location.reload();
```

---

## **Problem: Tracking funktioniert nicht trotz Zustimmung**

**Check 1:** LocalStorage
```javascript
JSON.parse(localStorage.getItem('analytics-consent'))
// Erwartet: { value: "accepted", expires: ... }
```

**Check 2:** Script geladen?
```javascript
document.querySelector('script[src="/analytics-und-so/datenblick.js"]')
// Erwartet: <script> Element
```

**Check 3:** Website-ID korrekt?
```javascript
document.querySelector('script[data-website-id]')?.dataset.websiteId
// Erwartet: "598ef5fd-d2dc-4540-9e65-602889981dac"
```

---

## **Problem: GPC wird nicht erkannt**

```javascript
navigator.globalPrivacyControl
// Firefox mit Tracking-Schutz: true
// Normale Browser: undefined
```

GPC ist optional - nicht alle Browser unterstützen es.

---

# API-REFERENZ

## **Public API (JavaScript)**

```javascript
// Banner anzeigen
CookieConsent.show();

// Banner verstecken
CookieConsent.hide();

// Settings Modal öffnen
CookieConsent.showSettings();

// Alle akzeptieren (programmatisch)
CookieConsent.acceptAll();

// Alle ablehnen (programmatisch)
CookieConsent.rejectAll();

// Status abfragen
const status = CookieConsent.getStatus();
/*
{
  consent: "accepted" | "rejected" | null,
  analytics: true | false,
  version: "2.0",
  timestamp: "2026-03-20T12:00:00Z",
  expires: 1774051200000,
  gpc: false
}
*/

// Sprache setzen
CookieConsent.setLanguage('en'); // oder 'de'
```

---

# CHANGELOG

## Version 2.0 (2026-03-20)

### Geändert:
- **Umstieg auf Umami v3.0.3** (ersetzt altes PHP-basiertes System)
- **Cookieless Tracking** - keine Cookies mehr nötig
- **Neues Tracking-Script:** `/analytics-und-so/datenblick.js`
- **Neuer API-Endpoint:** `/analytics-und-so/api/erfassen`
- **PostgreSQL** als Datenbank (ersetzt SQLite/Flatfile)
- **Rechtsgrundlage** auf Art. 6 I f DSGVO geändert (berechtigtes Interesse)
- **LocalStorage-Keys** umbenannt (`analytics-consent` statt `insights-consent`)
- Texte angepasst (keine Cookie-Referenzen mehr)
- Test-Checklisten gekürzt

### Entfernt:
- Cookie `_insights_session`
- PHP-Backend und zugehörige Konfiguration
- GeoIP-Datenbank (nicht mehr benötigt)
- Monatliche GeoIP-Update-Routine

## Version 1.0 (2025-11-09)

### Hinzugefügt:
- Custom Cookie Banner (Slim Layer Design)
- Settings Modal (Two-Step)
- GPC Support, Multilingual (DE/EN)
- LocalStorage mit Expiry, Consent Versioning
- Accessibility (ARIA, Focus-Trap), Responsive Design
- Public API, Datenschutzerklärung

---

# LIZENZ & CREDITS

**Erstellt für:** AegisSight UG
**Datum:** 2026-03-20
**Lizenz:** Proprietär (AegisSight)

**Rechtliche Hinweise:**
- Keine Garantie für vollständige Rechtssicherheit
- Datenschutzerklärung sollte von einem Anwalt geprüft werden
- Individuelle Anpassungen je nach Use Case erforderlich

---

**Status: PRODUKTIV**