Analytics-Integration

Wie v0- und Claude-gebaute Seiten auf das Cockpit-Analytics-System zugreifen – über MCP-Tools und ein wiederverwendbares Tracking-Snippet.

Überblick

Das Cockpit nutzt Umami als Analytics-Plattform. Jedes Center kann eine eigene Umami-Website-ID und -URL hinterlegen (Center-Einstellungen im Dashboard → Analytics). Externe Seiten (v0-Builds, Claude-Seiten) können:

1. Umami-Tracking einbetten → V0AnalyticsSnippet
2. Traffic-Statistiken lesen → MCP-Tool cockpit_analytics_website_stats
3. Content-Performance lesen → MCP-Tool cockpit_analytics_content_metrics
4. Benutzerdefinierte Events erfassen → MCP-Tool cockpit_analytics_track_event

---

MCP-Tools

Die Tools stehen im MCP-Server mcp-cockpit-os und können direkt aus Claude heraus genutzt werden. Voraussetzung: COCKPIT_AGENCYOS_API_KEY für geschützte Endpunkte (bei den Analytics-Routen optional, da diese intern sind).

cockpit_analytics_website_stats

Liest Website-Traffic-Statistiken für ein Center (Pageviews, Besucher, Absprungrate, Verweildauer) aus Umami.

Parameter

Parameter	Typ	Pflicht	Standard	Beschreibung
centerId	string (UUID)	✅	–	UUID des Centers
period	"24h" | "7d" | "30d" | "90d"	–	"30d"	Zeitraum der Statistiken
metric	"pageviews" | "visitors" | "sessions" | "bounce_rate" | "avg_duration"	–	–	Nur diese Metrik zurückgeben (optional)

Beispiel

cockpit_analytics_website_stats(
  centerId: "f1a2b3c4-...",
  period: "7d"
)

Antwort (Auszug)

{
  "success": true,
  "centerId": "f1a2b3c4-...",
  "centerName": "MEC Testcenter",
  "provider": "umami",
  "stats": {
    "pageviews": { "value": 12340, "prev": 10200 },
    "visitors": { "value": 3421, "prev": 2800 },
    "bounces": { "value": 1100, "prev": 980 },
    "totaltime": { "value": 450000, "prev": 400000 }
  },
  "pageviewsSeries": [ ... ]
}

Voraussetzung: Analytics muss für das Center aktiviert und eine Umami-Website-ID hinterlegt sein.

Dashboard: KI-Insights (intern)

GET /api/analytics/insights?centerId={uuid}&timeframe=day|week|month

• Session erforderlich (Dashboard-Nutzer)
• Liest Umami Stats + Events, generiert 3–5 Insights via gpt-4o-mini (OPENAI_API_KEY)
• UI: /dashboard/analytics → Teaser-Box im Tab Website + Tab KI-Insights
• Fokus stakeholder / limit=2 für die Teaser-Box; jedes Insight optional mit clientMessage (Text fürs Auftraggeber-Gespräch, im UI kopierbar)

---

cockpit_analytics_content_metrics

Liest Content-Performance-Metriken: Aufrufe und Klicks auf News, Angebote, Events, HotPicks.

Parameter

Parameter	Typ	Pflicht	Standard	Beschreibung
centerId	string (UUID)	✅	–	UUID des Centers
contentType	"news" | "offers" | "events" | "hotpicks" | "all"	–	"all"	Content-Typ filtern
period	"7d" | "30d" | "90d"	–	"30d"	Zeitraum
limit	number (1–50)	–	10	Anzahl der Top-Inhalte

Beispiel

cockpit_analytics_content_metrics(
  centerId: "f1a2b3c4-...",
  contentType: "news",
  period: "30d",
  limit: 5
)

Antwort (Auszug)

{
  "success": true,
  "data": {
    "totalViews": 8400,
    "totalEngagement": 312,
    "avgEngagementRate": 3.7,
    "topCategory": "News",
    "categoryBreakdown": [
      { "name": "News", "count": 24, "engagement": 200 },
      { "name": "Angebote", "count": 18, "engagement": 0 },
      { "name": "Events", "count": 12, "engagement": 0 }
    ]
  }
}

---

cockpit_analytics_track_event

Erfasst ein benutzerdefiniertes Nutzungs-Event. Events werden in der Datenbank gespeichert und erscheinen im monatlichen Reporting.

Parameter

Parameter	Typ	Pflicht	Standard	Beschreibung
centerId	string (UUID)	✅	–	UUID des Centers
eventType	string	✅	–	Art des Events, z.B. "page_view", "offer_click"
source	"website" | "kiosk" | "companion" | "app"	–	"website"	Quelle des Events
metadata	object	–	–	Zusätzliche Event-Daten (beliebig)

Beispiel

cockpit_analytics_track_event(
  centerId: "f1a2b3c4-...",
  eventType: "v0_page_load",
  source: "website",
  metadata: { page: "/angebote", referrer: "google" }
)

---

Tracking-Snippet für externe Seiten

V0AnalyticsSnippet

Eine React-Komponente (apps/center-website/components/analytics/v0-analytics-snippet.tsx) die das Umami-Tracking-Script in v0- oder Claude-gebaute Seiten einbettet.

Voraussetzungen

• Next.js (App Router oder Pages Router) mit next/script
• Das Center muss Analytics aktiviert und eine Umami-Website-ID hinterlegt haben

Props

Prop	Typ	Pflicht	Beschreibung
centerId	string	✅	UUID des Centers – wird für Multi-Tenant-Tracking genutzt
umamiWebsiteId	string	–	Umami-Website-ID (wenn nicht angegeben, wird sie über die API geladen)
umamiUrl	string	–	Basis-URL der Umami-Instanz (Standard: https://analytics.cockpit-os.de)

Verwendung

Einfachste Variante (Config wird automatisch geladen):

import { V0AnalyticsSnippet } from '@/components/analytics/v0-analytics-snippet'

export default function Layout({ children }) {
  return (
    <>
      <V0AnalyticsSnippet centerId="f1a2b3c4-uuid-des-centers" />
      {children}
    </>
  )
}

Mit expliziten Werten (kein API-Call nötig):

<V0AnalyticsSnippet
  centerId="f1a2b3c4-uuid-des-centers"
  umamiWebsiteId="abc123-umami-website-id"
  umamiUrl="https://analytics.cockpit-os.de"
/>

Verhalten

• Wartet auf Cookie-Consent des Nutzers (via vanilla-cookieconsent)
• In der Entwicklungsumgebung wird das Script ohne Consent-Check geladen (für Testzwecke)
• Wenn keine Website-ID gefunden wird, rendert die Komponente nichts (kein Fehler)
• Wenn Analytics für das Center deaktiviert ist, rendert die Komponente nichts

---

API-Endpunkte

Die MCP-Tools und das Snippet nutzen diese Dashboard-API-Routen:

Endpunkt	Methode	CORS	Beschreibung
/api/analytics/website-stats	GET	✅	Umami-Traffic-Statistiken für ein Center
/api/analytics/footfall	GET	–	Footfall-Dashboard (aktuell Mock/Platzhalter, siehe unten)
/api/analytics/usage-events	POST	✅	Benutzerdefinierte Events speichern
/api/content/metrics	GET	✅	Content-Performance-Metriken

Alle Endpunkte akzeptieren centerId als Query-Parameter (GET) bzw. im Request-Body (POST).

---

Footfall (Besucherströme)

Dashboard: /dashboard/analytics/footfall

API: GET /api/analytics/footfall?centerId=<uuid> (optional: ohne centerId nur generisches Portfolio-Beispiel)

Antwort (Schema): success, source (mock | live – produktiv noch mock), liveDataAvailable (bisher false), data mit summary, centers[], hourlyToday[], sowie message mit Erklärung.

• Mit echter Center-ID: Stammdatenname aus der DB, Kennzahlen Platzhalter (0/leer), bis eine Quelle (Sensoren, Import, Partner-API) angebunden ist – keine erfundenen Zahlen für Produktiv-Center.
• Ohne centerId: typisiertes Demonstrations-Portfolio nur für Layout/UX.

Typen und Mock-Builder: apps/dashboard/src/lib/analytics/footfall/. Live-Anbindung: fetchLiveFootfall in integration.ts – Schritt-für-Schritt: Footfall-API Vorbereitung.

Env (optional): FOOTFALL_PROVIDER, FOOTFALL_API_BASE_URL, FOOTFALL_API_KEY. Die API-Antwort enthält integration (Status für die Footfall-UI).

---

Architektur

Externe Seite (v0/Claude)
  │
  ├─► V0AnalyticsSnippet ──► Umami Script (direkt zum Umami-Server)
  │                           └─ Center-Config-API (/api/centers/{id}/public-config)
  │
  └─► cockpit_analytics_* (MCP-Tools)
        │
        ├─► /api/analytics/website-stats ──► Umami API (server-seitig)
        ├─► /api/content/metrics         ──► Prisma DB
        └─► /api/analytics/usage-events  ──► Prisma DB (CenterUsageEvent)

Datenfluss Tracking

1. Seitenaufruf: V0AnalyticsSnippet lädt das Umami-Script → Umami trackt Page Views direkt
2. Custom Events: cockpit_analytics_track_event schreibt in die Cockpit-DB (für Reporting)
3. Statistiken lesen: cockpit_analytics_website_stats fragt Umami über die server-seitige API ab

---

Verwandte Dokumentation

• v0-Website-Redaktion von A bis Z
• Öffentliche Center-Website-API
• AgencyOS-Integration