diff --git a/docs/anleitungen/Analytics.md b/docs/anleitungen/Analytics.md new file mode 100644 index 0000000..fc6b9aa --- /dev/null +++ b/docs/anleitungen/Analytics.md @@ -0,0 +1,981 @@ +# ANALYTICS-LÖSUNG: Implementierungsübersicht für Payload CMS + +*Letzte Aktualisierung: 18. Dezember 2025* + +## Kontext + +Du entwickelst das Multi-Tenant Payload CMS Backend und Next.js Frontend für 4 Websites. Diese Dokumentation beschreibt die Analytics-Lösung, die in das Frontend integriert werden muss. + +**Wichtig:** Frontends verwenden die **Production-API** (cms.c2sgmbh.de) und **Production-Analytics** (analytics.c2sgmbh.de). + +--- + +## Architektur-Übersicht + +``` +┌─────────────────────────────────────────────────────────────────────────────────────┐ +│ ANALYTICS ARCHITEKTUR │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────────┐ │ +│ │ OHNE CONSENT (immer aktiv) │ │ +│ │ │ │ +│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ UMAMI ANALYTICS │ │ │ +│ │ │ │ │ │ +│ │ │ Server: sv-analytics (10.10.181.103:3000) │ │ │ +│ │ │ Dashboard: http://10.10.181.103:3000 │ │ │ +│ │ │ Script: /custom.js (Anti-Adblock) │ │ │ +│ │ │ Endpoint: /api/send │ │ │ +│ │ │ │ │ │ +│ │ │ Features: │ │ │ +│ │ │ • Cookieless Tracking (DSGVO-konform ohne Einwilligung) │ │ │ +│ │ │ • Pageviews, Sessions, Referrer, UTM-Parameter │ │ │ +│ │ │ • Custom Events (Newsletter, Formulare, CTAs, Downloads) │ │ │ +│ │ │ • 100% Erfassung aller Besucher │ │ │ +│ │ └─────────────────────────────────────────────────────────────────────┘ │ │ +│ └─────────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────────┐ │ +│ │ MIT CONSENT (Kategorie: "marketing") │ │ +│ │ │ │ +│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ GOOGLE ADS CONVERSION │ │ │ +│ │ │ │ │ │ +│ │ │ Client-Side (bei Consent): │ │ │ +│ │ │ • Google Ads Tag (gtag.js) │ │ │ +│ │ │ • Conversion Tracking │ │ │ +│ │ │ • Remarketing Audiences │ │ │ +│ │ │ │ │ │ +│ │ │ Server-Side (immer, anonymisiert): │ │ │ +│ │ │ • Google Ads Conversion API │ │ │ +│ │ │ • Enhanced Conversions (gehashte E-Mail) │ │ │ +│ │ │ • GCLID-basierte Attribution │ │ │ +│ │ └─────────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ GOOGLE CONSENT MODE v2 │ │ │ +│ │ │ │ │ │ +│ │ │ Integration mit bestehendem Orestbida Consent-Banner │ │ │ +│ │ │ Kategorie "marketing" steuert: │ │ │ +│ │ │ • ad_storage │ │ │ +│ │ │ • ad_user_data │ │ │ +│ │ │ • ad_personalization │ │ │ +│ │ └─────────────────────────────────────────────────────────────────────┘ │ │ +│ └─────────────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Infrastruktur + +### Umami Server + +| Umgebung | Server | URL | Dashboard | +|----------|--------|-----|-----------| +| **Production** | Hetzner 3 | https://analytics.c2sgmbh.de | https://analytics.c2sgmbh.de | +| **Development** | sv-analytics (LXC 703) | https://umami.porwoll.tech | https://umami.porwoll.tech | + +| Eigenschaft | Production | Development | +|-------------|------------|-------------| +| **Tracking Script** | https://analytics.c2sgmbh.de/script.js | https://umami.porwoll.tech/script.js | +| **API Endpoint** | https://analytics.c2sgmbh.de/api/send | https://umami.porwoll.tech/api/send | +| **Datenbank** | umami_db auf Hetzner 3 | umami_db auf sv-postgres | + +### Website-IDs (Multi-Tenant) + +Die Website-IDs werden in Umami für jeden Tenant erstellt: + +```typescript +// src/config/analytics.ts + +export const UMAMI_WEBSITE_IDS: Record = { + 'porwoll.de': 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', + 'complexcaresolutions.de': 'yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy', + 'gunshin.de': 'zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz', + 'zweitmeinu.ng': 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa', +} + +// Production URL für Frontends +export const UMAMI_HOST = process.env.NEXT_PUBLIC_UMAMI_HOST || 'https://analytics.c2sgmbh.de' +``` + +--- + +## Frontend-Integration + +### 1. Umami Script Komponente + +```typescript +// src/components/analytics/UmamiScript.tsx + +'use client' + +import Script from 'next/script' + +interface UmamiScriptProps { + websiteId: string + host?: string +} + +export function UmamiScript({ + websiteId, + host = 'https://analytics.c2sgmbh.de' // Production default +}: UmamiScriptProps) { + if (!websiteId) return null + + return ( +