v0 / Vercel: Parallele Frontends (Website, Signage, Companion)

Zielgruppe: Redaktion, IT und v0-Entwickler.

Grundsatz: Cockpit bleibt — v0 kommt dazu

cockpitOS betreibt weiterhin eigene Frontends auf *.cockpit-os.de. v0/Vercel ist ein zusätzlicher Kanal für Layout/UI — kein Ersatz.

Oberfläche	Cockpit-Kanal (bleibt)	Zusätzlich v0/Vercel
Center-Website	Preview `preview.cockpit-os.de/{slug}`, Custom Domain (Website-Tab)	Optionales Vercel-Projekt, gleiche API

Ausnahme — v0-only Templates (forum-gummersbach, mec-template-small-assets): kein Layout unter preview.cockpit-os.de. Vorschau nur über Preview-/Staging-URL (Frontend-Kanäle) bzw. Live-Domain. | Signage / Kiosk | {center}.signage.cockpit-os.de | z. B. signage-xyz.vercel.app | | Companion / NOW! | Signage-Origin + /companion… | gleiche oder eigene Vercel-URL |

Daten & API für alle Kanäle: https://dashboard.cockpit-os.de (NEXT_PUBLIC_DASHBOARD_URL).

                    ┌─────────────────────────┐
                    │  dashboard.cockpit-os.de │
                    │  (Inhalte, APIs, CMS)    │
                    └───────────┬─────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        │                       │                       │
        ▼                       ▼                       ▼
 Cockpit-Website          Cockpit-Signage           v0/Vercel
 preview + Domain         *.signage…                (optional,
 (bestehend)              (bestehend)                pro Fläche)

Redaktion: So wenig Handarbeit wie möglich (v0-first)

Grundsatz: Redaktion startet in v0 (Instructions A–I + D). Inhalte landen per MCP im Cockpit. Nach Vercel-Deploy meldet sich das Projekt selbst ans Cockpit (Teil J).

Schritt	Wer	Was passiert
1	Redaktion	In v0 bauen + Inhalte (Shops, News, …) — Teil D → Cockpit
2	IT (einmalig)	Vercel: Register-Token + `/api/cockpit-register` + Deploy Hook
3	System	Nach Deploy: Cockpit kennt Live-URL automatisch
4	Live	Änderungen in v0-Chat oder Cockpit — gleiche DB, Auto-Revalidate

Dashboard Frontend-Kanäle = Status/Fallback unter Website-Management → Frontend-Kanäle (v0), nicht der Hauptweg.

API: POST /api/public/frontend-deployments/register · MCP: cockpit_register_frontend_deployment

Dashboard: Frontend-Kanäle (ein Ort)

Website-Management → Frontend-Kanäle (v0) — /dashboard/website/frontend-kanaele

Pro Kanal wählbar: Cockpit oder v0/Vercel (websiteHostingChannel, signageHostingChannel, companionHostingChannel). Alle Kombinationen sind möglich (z. B. Website Cockpit, Signage v0, Companion Cockpit).

Die Seite zeigt nur relevante Reiter und Optionen:

Bedingung	Was erscheint
Website-Reiter	Hosting-Auswahl Cockpit-Website vs. v0; bei v0: URLs, Verbindungstest
v0-only Template	Keine Zeile „Cockpit-Vorschau“; Hinweis + klickbare v0-Staging-URL
Signage-Reiter	Nur wenn Digital Experience + Signage aktiv; eigene Hosting-Auswahl
Companion-Reiter	Nur wenn Companion aktiv; eigene Hosting-Auswahl
Reiter Technik	DNS/Go-Live (Website), Register-Token für v0-Deploys

Reiter: Website (immer), optional Signage, Companion, Technik (Hosting & DNS immer).

API liefert channelVisibility in GET /api/centers/{centerId}/signage-public-urls.

Custom Domains der Website weiter im Tab Center → Website (Cockpit-Hosting).

API: GET/PATCH /api/centers/{centerId}/signage-public-urls (Website + Signage + Companion).
Verbindungstest: POST …/signage-public-urls/test-connection.

Signage & Companion aus v0-Layout

Was: Kiosk/Stele und NOW!-Companion können als eigenes v0/Vercel-Projekt laufen — Layout und UI in v0, Inhalte und APIs weiter im Cockpit.

Warum: Redaktion/Agentur will ein individuelles Terminal- und Handy-Design (Instructions Teil H + I), ohne das Cockpit-Signage-Template zu ersetzen. Cockpit bleibt Single Source of Truth für Shops, Plan, News usw.

Wer ist betroffen: Redaktion (Inhalte im Cockpit), IT/v0 (Vercel + Register), Center-Betrieb (Stelen im Einsatz).

Wo: Dashboard Website-Management → Frontend-Kanäle — Reiter Signage, Companion, Technik. v0-Instructions: Teil H & I, System-Infos Kiosk+Companion.

Digital Experience → Signage (`/dashboard/digital-experience/signage`)

Diese Seite bleibt für Aktivierung, Content und Status — die öffentlichen URLs kommen aus GET /api/centers/{centerId}/signage-config (Hosting-Kanal aus Frontend-Kanäle).

Tab	Bei v0-Hosting
Aktivierung	Schalter + URLs mit Badge „v0 / Vercel“; Subdomain nur für optionales paralleles Cockpit-Signage
Konfiguration	Kiosk-Konfiguration mit Speichern; URLs + parallele Cockpit-URLs; v0-Hinweis
Content	Unverändert — Cockpit bleibt CMS
Analytics	Links zu Companion QR-Sessions und Analytics (Cockpit erfasst auch v0)

So testen: Frontend-Kanäle → Signage auf v0 stellen → Signage-Seite → „App öffnen“ zeigt die Vercel-URL, nicht *.signage.cockpit-os.de.

Digital Experience → Companion (`/dashboard/digital-experience/companion`)

Tab	Bei v0-Hosting
Übersicht	Aktivierung mit Speichern; Companion-URL mit Badge „v0 / Vercel“; parallele Cockpit-URL
QR-Sessions	Hinweis auf Handoff POST/PATCH aus v0 Teil H/I
Konfiguration	Speichern für Features/Branding; Hinweis dass Layout in v0, Daten im Cockpit
App öffnen (Header)	Vercel-URL aus `signage-config`, nicht Cockpit-Signage-Origin

So testen: Frontend-Kanäle → Companion auf v0 → Companion-Seite → „App öffnen“ zeigt die Vercel-URL.

Empfohlenes v0-Setup (ein Projekt, zwei Oberflächen)

Route	Oberfläche
`/kiosk` oder `/signage`	Stele (55″, Terminal-Layout — Teil H)
`/companion`	NOW!-App fürs Handy (Teil I)

Gemeinsam: APIs, Centerplan, Branding. Getrennt: Kiosk-Shell vs. Companion-Shell.

Checkliste: Cockpit + v0

Schritt	Wer	Aktion
1	v0	Projekt mit Teil H + I bauen (`/kiosk` + `/companion`, Handoff-QR, Revalidate-Route)
2	IT	Vercel: Register-Token aus Reiter Technik, Deploy-Hook → Teil J
3	Redaktion/IT	Frontend-Kanäle → Reiter Signage: Hosting v0 / Vercel; URL eintragen oder nach Deploy automatisch
4	Redaktion/IT	Reiter Companion: Hosting v0 / Vercel; bei gleicher Origin Companion-URL leer (Cockpit leitet `/companion…` ab)
5	Redaktion	Inhalte im Cockpit pflegen (oder per MCP) — v0 liest öffentliche APIs (Teil A)
6	Test	Handoff: Kiosk-QR → Companion mit `sessionKey`; Publish im Cockpit → Revalidate → Live auf Stele/Companion

Vercel-Env (Signage-Projekt): COCKPIT_REGISTER_TOKEN, COCKPIT_CENTER_SLUG, NEXT_PUBLIC_DASHBOARD_URL, Team Shared: REVALIDATION_SECRET, COCKPIT_FRONTEND_CHANNEL=signage (bzw. companion bei separatem Melden).

Mischbetrieb (Hosting pro Kanal)

Kombination	Empfehlung
Website Cockpit + Signage v0 + Companion v0	Häufig — Website auf Render, Kiosk/Companion in v0
Signage v0 + Companion v0 (ein Projekt)	Standard für v0-Signage
Signage v0 + Companion Cockpit	Nur mit angepasstem Handoff-QR (Ziel = Cockpit-Companion-URL)
Signage Cockpit + Companion v0	Separates Companion-v0-Projekt + `companionPublicUrl`

Faustregel: Kiosk und Companion aus demselben v0-Projekt → beide Reiter auf v0 / Vercel stellen.

Was v0 implementieren muss

Handoff: POST /api/public/handoff-sessions → Link /companion?centerId=…&sessionKey=…
Daten: public-visitor-surface, floors, shops, aktuelles-bundle — keine hardcodierte centerId
Deploy: app/api/revalidate/route.ts + Register nach Deploy (v0-deploy-cockpit-register)
Tracking (optional): Umami app=companion + POST /api/analytics/usage-events

So testen (Tracking)

v0-Kiosk: POST /api/public/handoff-sessions → Session im Tab Companion → QR-Sessions sichtbar.
v0-Companion beim Öffnen: PATCH /api/public/handoff-sessions mit { sessionKey, centerId, companionOpened: true } → Dauer/Aktivität im Dashboard.
Journey-Schritte: POST /api/analytics/usage-events mit { centerId, source: "companion", eventType: "qr_scan", payload: { sessionKey } } → Reporting + optional Session-Touch.
Umami: Script via /api/umami-app-config?app=companion, Events mit center_id; Companion-URLs mit ?centerId= oder ?center=slug für Center-gefilterte Pageviews im Dashboard.

v0-Schnellreferenz Tracking

// 1) QR am Kiosk
const { data } = await fetch(`${DASHBOARD}/api/public/handoff-sessions`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ centerId, touchscreenId: 'v0-kiosk', location: { source: 'v0' } }),
}).then((r) => r.json());

// 2) Companion geöffnet (nach QR-Scan)
await fetch(`${DASHBOARD}/api/public/handoff-sessions`, {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    sessionKey: data.sessionKey,
    centerId,
    companionOpened: true,
  }),
});

// 3) Journey / Reporting (pro Center, Cockpit-DB)
await fetch(`${DASHBOARD}/api/analytics/usage-events`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    centerId,
    source: 'companion',
    eventType: 'companion_journey',
    payload: { sessionKey: data.sessionKey, step: 'qr_scan' },
  }),
});

// 4) Umami (nach Consent) — center_id in Custom Events

Betrieb: Keine Schema-Änderung nötig — nur APIs und v0-Integration. Bestehende QRSession-Zeilen bleiben unverändert.

Was parallel funktioniert

Gleiche Inhalte auf Cockpit-Website und v0-Website (Shops, News, Plan, …)
Cockpit-Signage und v0-Kiosk am selben Center
Analytics: Umami/Tracking pro Center — auch von Vercel-Origins, wenn eingebunden
Handoff QR-Sessions: POST /api/public/handoff-sessions — sichtbar im Dashboard unabhängig vom Frontend-Host
Standort-QRs (Service/Shop/Park/NOW!/extern): stabile Einstiegs-URL auf aktiver Domain; Auflösung über GET /api/public/qr-codes/{qrCodeId}/resolve oder POST …/scan (Track+Resolve) — v0 implementiert /companion/qr/[qrCodeId] (Teil I)

v0 Checkliste

Immer:
  NEXT_PUBLIC_DASHBOARD_URL=https://dashboard.cockpit-os.de

Website (v0):
  Center-Auflösung: by-domain ODER ?center=slug (Preview)
  Optional im Dashboard: websitePublicUrl eintragen

Signage (v0):
  /kiosk + /companion im selben Projekt (Handoff)
  /companion/qr/[qrCodeId] — Standort-QR-Resolver (GET resolve oder POST scan + Redirect)
  POST + PATCH /api/public/handoff-sessions
  POST /api/analytics/usage-events (Reporting pro Center)

Nicht:
  Cockpit-URLs als API-Basis verwenden
  Annehmen, dass v0 die Cockpit-Hostings abschaltet

Statistik

Kanal	Cockpit sichtbar	v0 sichtbar wenn …
Website Umami	Website-Tab / Tracking-Config	`public-visitor-surface` → tracking eingebunden
Companion/Kiosk (Umami)	Companion → Analytics	`umami-app-config?app=companion` + `center_id` in Events; URLs mit `centerId`/`slug` für Center-Filter
QR-Handoff-Sessions	Companion → QR-Sessions	`POST` + `PATCH /api/public/handoff-sessions`
Standort-QR-Scans	QR-Management / Analytics	`POST /api/public/qr-codes/{id}/scan` (bevorzugt) oder `GET …/resolve` + `POST …/track`; v0-Route `/companion/qr/[id]`
Usage-Events (Reporting)	Companion → Analytics	`POST /api/analytics/usage-events` mit `centerId`

Siehe auch

Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /digital-signage/v0-vercel-hosting-dashboard-statistik

Grundsatz: Cockpit bleibt — v0 kommt dazu​

Redaktion: So wenig Handarbeit wie möglich (v0-first)​

Dashboard: Frontend-Kanäle (ein Ort)​

Signage & Companion aus v0-Layout​

Digital Experience → Signage (/dashboard/digital-experience/signage)​

Digital Experience → Companion (/dashboard/digital-experience/companion)​

Empfohlenes v0-Setup (ein Projekt, zwei Oberflächen)​

Checkliste: Cockpit + v0​

Mischbetrieb (Hosting pro Kanal)​

Was v0 implementieren muss​

So testen (Tracking)​

v0-Schnellreferenz Tracking​

Was parallel funktioniert​

v0 Checkliste​

Statistik​

Siehe auch​