# Web-Displays

Ein Web-Display ist ein Display, hinter dem kein Gerät steht, sondern ein Browser-Tab. Diese Seite nennt die Routen, den Weg vom Anlegen bis zum ersten Bild, die beiden Zustände, in denen es leben kann, und die Grenzen, die es von einem Gerät unterscheiden.

> **Typ:** nachschlagen
> **Für wen:** Wer Displays aus einem eigenen System heraus anlegt oder einen Assistenten etwas zeigen lassen will, ohne dass jemand Hardware anschließt.
> **Voraussetzung:** ein Schlüssel `ak_…` mit dem Recht `fleet.web-display.manage` — es ist schlüsselfähig und delegierbar. Die Organisation braucht außerdem die Fähigkeit **Displays ohne Agent**.

## Was ein Web-Display ist

Ein vollwertiges Display der Flotte: Es hat eine Kennung `ply_…`, einen Namen, einen Standort, ein Programm und einen gebuchten Platz. Was ihm fehlt, ist die Maschine — es läuft in einer Browser-Seite, und seine ganze Identität ist ein Geheimnis in der Ablage dieses Browsers.

Daraus folgt das Eigentümliche dieses Weges: **Anlegen und Anschließen sind zwei Schritte, und den zweiten kann kein Programm tun.** Die Plattform legt das Display an und stellt eine Adresse aus; ein Mensch muss diese Adresse auf dem Zielgerät im Browser öffnen. Bis dahin steht das Display im Zustand `paired-not-claimed` — in der Oberfläche „nicht verbunden“.

| Zustand | Bedeutung |
|---|---|
| `paired-not-claimed` | angelegt, aber noch kein Browser hat die Adresse geöffnet. Belegt bereits einen gebuchten Platz. |
| `online` / `stale` / `offline` | ein Browser hängt daran; der Zustand kommt wie bei jedem Display aus dem Alter des letzten Lebenszeichens |

## Die Routen

| Route | Recht | Bemerkung |
|---|---|---|
| `POST /v1/web-displays` | `fleet.web-display.manage` oder `fleet.player.pair` | `201`; legt Display und Anschluss-Adresse in einem Zug an |
| `POST /v1/web-displays/{id}/link` | `fleet.web-display.manage` oder `fleet.player.pair` | `201`; eine neue Adresse für ein bestehendes Web-Display |
| `POST /v1/web-displays/batch` | `fleet.web-display.manage` oder `fleet.player.pair` | `201`; legt bis zu 50 Displays in einem Zug an (`count`, optional `locationId` und `namePrefix`), mit durchnummerierten Namen und je einer Anschluss-Adresse. Alles oder nichts: Reichen die gebuchten Plätze nicht, entsteht keines. Die Antwort hat die Form einer Provisionierungs-Datei, jede Adresse gilt einmal und verfällt nach 24 Stunden |
| `DELETE /v1/web-displays/{id}` | `fleet.web-display.manage` | nimmt Display und Browser-Zugang aus dem Bestand |
| `GET /v1/web-displays/address` | `fleet.web-display.manage` oder `fleet.player.pair` | die Adresse der Anzeige-Anwendung — für Bildschirme, auf die sich keine Adresse kopieren lässt |

Alle Routen tragen `x-stability: beta`, auch `POST /v1/web-displays/batch`. Ihre Form kann sich noch bewegen; der Weg selbst hat sich mit dieser Welle bereits einmal verschoben (früher entstand das Display erst beim Öffnen des Links).

Zum Löschen gilt: `fleet.player.pair` genügt hier **nicht**. Wer das Kopplungsrecht hält, hat ein Recht zum Anschließen erteilt bekommen und keines zum Wegräumen; ihm hier stillschweigend eines mitzugeben, machte aus einer alten Zustimmung eine neue.

## Anlegen und anschließen

```bash
curl -sS -X POST "$SZENERA_API/v1/web-displays" \
  -H "Authorization: Bearer $SZENERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Schaufenster links", "locationId": "loc_01KFB7QPW0LOCATION00000001" }'
```

```json
{
  "playerId": "ply_01KFB7QPW0PLAYER0000000001",
  "token": "drc_01KFB7QPW0TOKEN00000000001",
  "connectUrl": "https://webplayer.szenera.com/?reconnect=drc_01KFB7QPW0TOKEN00000000001",
  "expiresAt": "2026-09-11T10:00:00.000Z"
}
```

`connectUrl` ist die Adresse für den Menschen am Zielgerät. Sie beginnt mit der Adresse der Anzeige, die auch `GET /v1/web-displays/address` nennt, und gilt **einmal**: Sobald ein Browser sie geöffnet hat, ist die Marke verbraucht. Die Frist hängt daran, ob schon ein Browser an diesem Display hängt — bei der ersten Adresse 24 Stunden, danach zwei.

Ein Startprogramm ist an dieser Route bewusst **nicht** vorgesehen. Die Zuweisung hat ihre eigene Route mit ihren eigenen Prüfungen; ein Display mit Inhalt entsteht deshalb in zwei Aufrufen:

```bash
curl -sS -X PUT "$SZENERA_API/v1/scheduling/players/ply_01KFB7QPW0PLAYER0000000001/program" \
  -H "Authorization: Bearer $SZENERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "program": { "kind": "schedule", "scheduleId": "sch_01KFB7QPW0SCHEDULE0000001" } }'
```

Die Reihenfolge ist gleichgültig: Ein Display, dem vor dem Anschluss ein Programm zugewiesen wurde, zeigt es, sobald der Browser da ist.

## Eine neue Adresse

Der Anlass ist immer derselbe: Der Browser weiß nicht mehr, dass er dieses Display ist — geleerter Speicher, frisches Profil, anderer Rechner — oder die erste Adresse ist abgelaufen, ohne dass jemand sie geöffnet hat.

```bash
curl -sS -X POST "$SZENERA_API/v1/web-displays/ply_01KFB7QPW0PLAYER0000000001/link" \
  -H "Authorization: Bearer $SZENERA_API_KEY"
```

Wer die neue Adresse öffnet, übernimmt das Display. Der Browser, der es bis dahin zeigte, verliert es samt seinen laufenden Renderer-Sitzungen, und alle älteren offenen Adressen desselben Displays verfallen. Name, Standort, Programm, Verlauf und der gebuchte Platz bleiben unberührt — genau darin unterscheidet sich dieser Weg vom Neuanlegen.

## Löschen

```bash
curl -sS -X DELETE "$SZENERA_API/v1/web-displays/ply_01KFB7QPW0PLAYER0000000001" \
  -H "Authorization: Bearer $SZENERA_API_KEY"
```

Es verschwinden **beide Hälften**: das Display in der Flotte und das Browser-Gerät dahinter. Der gebuchte Platz wird frei, Programm, Übersteuerung und Verlauf werden aufgelöst. Ein Display mit Gerät wird an dieser Route abgewiesen — dafür gibt es `DELETE /v1/players/{id}`, und das bleibt einem Menschen in einer Sitzung vorbehalten.

## Was ein Web-Display nicht kann

Hinter der Fläche steht keine Maschine, die sich steuern ließe. Das ist keine Lücke der Schnittstelle, sondern die Beschaffenheit der Sache:

| Nicht möglich | Warum |
|---|---|
| Systemabbild, Kanal, Rückfallebene | Browser und Betriebssystem pflegt, wer den Rechner betreut |
| Bildschirm ein- und ausschalten, Panel-Helligkeit | CEC und DDC/CI sprechen die Maschine am Kabel an, nicht eine Seite im Browser |
| Neustart der Maschine | Neu geladen wird der Tab; der Rechner bleibt unberührt |
| Bildschirmfoto ohne Erweiterung | Kein Web-Standard erlaubt einer Seite, sich selbst zu fotografieren |
| Zwei Bildschirme an einem Browser | Ein zweiter braucht ein zweites Browser-Profil und wird ein eigenes Display mit eigenem Platz |

## Wenn etwas nicht klappt

| Symptom | Bedeutung | Lösung |
|---|---|---|
| `409 WebDisplay.NotABrowserDisplay` | Hinter der Kennung steht ein Display mit Gerät. | `DELETE /v1/players/{id}` bzw. `POST /v1/devices/{id}/reconnect-link` — beide für Menschen in einer Sitzung. |
| `402 Billing.LicensesExhausted` | Alle gebuchten Plätze sind belegt. Die Antwort nennt `booked` und `used`. | Einen Platz dazubuchen oder ein nicht mehr gebrauchtes Display löschen. |
| `403 Billing.FeatureNotEntitled` | Die Fähigkeit **Displays ohne Agent** ist für diese Organisation abgeschaltet. | Beim Betreiber der Plattform freischalten lassen. |
| `404 Location.NotFound` beim Anlegen | Die genannte Standort-Kennung gehört zu keinem Ort dieser Organisation. | Kennung aus `GET /v1/locations` nehmen. |
| Die Adresse führt auf einen Kopplungscode | Die Marke war verbraucht oder abgelaufen, der Browser hat sich daraufhin als neues Gerät angemeldet. | Eine neue Adresse ausstellen und diese öffnen; das leere Gerät bleibt ungekoppelt und verfällt. |

## Weiterführendes

- [Der MCP-Dienst](/de/api/mcp-service) — die Werkzeuge `create_web_display`, `issue_web_display_link` und `delete_web_display`
- [Standorte](/de/api/locations)
- [Fehlercodes: Geräte, Wiedergabe, Meldungen, Betrieb](/de/api/error-codes-devices-operations)