Skip to main content

screenCockpit Center-Pairing (Magic-Link)

Was​

Im Dashboard unter Digital Experience → DOOH Video gibt es die Karte screenCockpit. Ein Center kann sich dort mit genau einem Standort in screenCockpit (DOOH-Signage-Plattform) verbinden: Verbinden, Verbindung testen, Trennen. Gespeichert werden pro Center Standort-ID, Name, Code, Berechtigungen und der verschlüsselte API-Key.

Bewusst nicht Teil des Pairings: Playlist-Editor und Content-Push-Assistent im Dashboard. Read-only Playlist-Liste am verbundenen Standort: siehe unten.

Warum​

screenCockpit vergibt API-Keys pro Standort. Bisher musste ein Admin Keys von Hand anlegen und weitergeben. Der Magic-Link-Flow (wie bei AgencyOS) vermeidet Copy-Paste von Geheimnissen: Die Freigabe passiert einmalig in screenCockpit, cockpitOS übernimmt den Key automatisch.

Wer ist betroffen​

  • Center-Betrieb / Redaktion (Rollen mit Redaktions- und Technikzugriff und Center-Zugang): verbinden, testen, trennen.
  • IT / Betrieb: Env-Variablen setzen, Key bei Bedarf in screenCockpit widerrufen.

Ablauf​

  1. Dashboard POST /api/centers/{centerId}/screencockpit/connect ruft screenCockpit POST /api/agencyos/magic-link auf (Header X-AgencyOS-Secret, returnUrl = Dashboard-DOOH-Seite mit screencockpit=return&centerId=…). Antwort: token, magicLink.
  2. Das Dashboard speichert den Link als PENDING (lokal 14 Minuten gültig, screenCockpit: ca. 15 Minuten) und öffnet magicLink in einem neuen Tab.
  3. Admin meldet sich in screenCockpit an, wählt den Standort und klickt Zugriff erlauben; screenCockpit leitet zurück zur returnUrl (agencyos=connected|rejected).
  4. Die Karte pollt GET …/screencockpit/status (alle 4 s, solange PENDING). Der Server fragt GET /api/agencyos/magic-link/status?token=… ab.
  5. Bei completed liefert screenCockpit den apiKey nur einmal. cockpitOS verschlüsselt ihn sofort (AES-256-GCM) und liest danach GET /api/v1/context für Standort-ID/-Name/-Code und Scopes.
  6. Link-Token und Magic-Link-URL werden gelöscht, Status CONNECTED.

Robustheit:

  • Paralleles Polling (mehrere Tabs): atomarer Claim (poll_claimed_at, 15 s), damit nur ein Request den einmaligen Key abholt.
  • Key da, Kontext-Abruf scheitert: Verbindung wird trotzdem gespeichert (Key ist nicht erneut abrufbar); …/test zieht Standort-Mapping nach.
  • completed ohne Key (bereits abgeholt): Status FAILED, Hinweis „Bitte neu verbinden“.
  • Netzwerkfehler beim Poll: Link bleibt PENDING, nächster Poll versucht es erneut.
  • Bereits verbunden: connect antwortet 409; zuerst trennen.

API (Dashboard, Session + Center-Zugriff)​

Alle Routen unter /api/centers/{centerId}/screencockpit/…; Rollen wie Redaktion/Technik (EDITORIAL_AND_TECH_ROLES) plus assertCenterAccess. Antworten enthalten nie den API-Key oder das Magic-Link-Token.

MethodePfadZweck
POST/connectMagic-Link starten (oder gültigen offenen Link wiederverwenden)
GET/statusStatus; pollt bei PENDING screenCockpit und übernimmt den Key
POST/testGET /api/v1/context mit gespeichertem Key, aktualisiert Standort + last_tested_at
POST/disconnectLink und Key lokal löschen (funktioniert auch ohne Env-Konfiguration)
GET/playlistsRead-only Proxy zu screenCockpit GET /api/v1/playlists?locationId=… (Key X-Api-Key, Scopes siehe oben)
GET, PUT/idle-sourceIdle-Quelle des Kiosks: { idleDoohSource: cockpit | screencockpit, idleScreenCockpitPlaylistId }. PUT mit screencockpit verlangt eine Playlist-ID. Der Kiosk liest die Items serverseitig über GET /api/v1/playlists/{id}/items?activeOnly=true (siehe Kiosk-Idle). Hinweis: GET …/playlists liefert pro Playlist itemCount (gesamt); die Items-API mit activeOnly=true kann weniger Zeilen zurückgeben (Zeitplan upstream in screenCockpit). cockpitOS mappt VIDEO/IMAGE mit abspielbarer URL: http(s)://… oder root-relative /uploads/… (wird gegen SCREENCOCKPIT_BASE_URL absolut gemacht) — Abweichungen erscheinen in Render-Logs unter [dooh-idle-screencockpit].

Standard-Magic-Link-Keys haben oft content:push und status:read. Für die Playlist-Übersicht im Dashboard braucht der Key playlists:read (oder weiterhin content:push, das Listen erlaubt). Fehlt beides, zeigt die UI einen Hinweis zum Neu-Verbinden mit erweiterter Freigabe in screenCockpit.

Team-Regeln (Kiosk vs. Wand-Player): DOOH & Signage — Zuständigkeiten.

Datenmodell​

Tabelle center_screencockpit_links (Prisma CenterScreenCockpitLink), ein Eintrag pro Center, ON DELETE CASCADE. Rein additiv, keine Änderung an ShoppingCenter-Spalten. Siehe db_structure.md. Migration: packages/database/migrations/20261019120000_center_screencockpit_link_SAFE.sql.

Status: PENDING, CONNECTED, REJECTED, EXPIRED, FAILED.

Betrieb (Env, keine Secrets in Doku)​

VariablePflichtBedeutung
SCREENCOCKPIT_BASE_URLjaBasis-URL der screenCockpit-Instanz, z. B. https://… (nur Origin wird genutzt)
SCREENCOCKPIT_AGENCYOS_MAGIC_LINK_SECRETin Produktion jaGleicher Wert wie AGENCYOS_MAGIC_LINK_SECRET bei screenCockpit; wird als X-AgencyOS-Secret gesendet
SCREENCOCKPIT_TOKEN_KEYempfohlenSchlüssel für die Verschlüsselung der gespeicherten API-Keys. Fehlt er, wird NEXTAUTH_SECRET genutzt (bei dessen Rotation muss neu verbunden werden)

Ohne Konfiguration zeigt die Karte einen Hinweis; connect/test antworten 503. Das Ziel (SCREENCOCKPIT_BASE_URL) ist fest per Env — keine nutzergelieferten URLs, daher kein SSRF-Pfad. Magic-Link-URLs aus der Antwort müssen http(s) sein.

So testen​

  1. Env setzen (Render mallos-dashboard bzw. .env.local), Migration einspielen.
  2. Dashboard → Digital Experience → DOOH Video, Center wählen → Mit screenCockpit verbinden.
  3. In screenCockpit Standort wählen, Zugriff erlauben. Zurück im Dashboard: Status Verbunden, Standort sichtbar.
  4. Verbindung testen → Erfolgsmeldung; mit widerrufenem Key → Hinweis „neu verbinden“.
  5. Trennen → Karte zeigt wieder Mit screenCockpit verbinden.

Automatische Tests: pnpm --filter @mall-os/dashboard exec vitest run src/lib/screencockpit.

Code​

  • apps/dashboard/src/lib/screencockpit/ — config.ts, client.ts (HTTP), link-state.ts (reine Logik), link-service.ts (Orchestrierung), link-store.ts (Prisma), secret-crypto.ts, route-helpers.ts
  • apps/dashboard/src/components/screencockpit/ — Karte + Hook
  • Vertrag der Gegenseite: Repo smg-dooh-light, docs/AGENCYOS_INTEGRATION.md

Nicht in dieser Lieferung​

MCP-Tool/AgencyOS-Route für Playlists: bewusst nicht ergänzt. Content-Push-Assistent und Schreibzugriff folgen in Epic PR-2 (Skizze in project_specs.md, Abschnitt „Content-Push nach screenCockpit“).

Nutzer-Sicht: DOOH-Modus im Kiosk, Zuständigkeiten.

Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /en/developer-guide/screencockpit-center-pairing