Zum Inhalt springen
ENKostenlos testen
Anleitung

Ein Display anlegen und bespielen

Displays nach eigener Liste ausrollen: jedes mit Namen und Standort anlegen, ein Programm zuweisen und die Adresse für den Fernseher weitergeben.

3 Min LesezeitStand 30. Okt. 2026Als Markdown
Für wen
Entwicklerinnen und Entwickler, die Displays aus dem eigenen System einrichten
Voraussetzung
ein Schlüssel ak_… der Klasse Individuell mit fleet.web-display.manage, location.list und schedule.update, und für Ihre Organisation die Fähigkeit Displays ohne Agent
Ort
Kommandozeile
Auf dieser Seite

Am Ende steht ein neues Display mit Namen und Standort in Ihrer Flotte, es hat schon ein Programm, und der Fernseher muss nur noch eine Adresse öffnen. So rollen Sie Displays nach Ihrer eigenen Liste aus, etwa nach den Filialen in einer Tabelle.

Warum ein Web-Display

Ein Web-Display braucht kein eigenes Gerät. Die API legt es mit einem Aufruf an, und jemand öffnet seine Adresse im Browser des Fernsehers. Geräte, die einen sechsstelligen Code zeigen, werden dagegen mit POST /v1/pairings/claim gekoppelt. Dafür braucht es das Recht fleet.player.pair, und das kann kein API-Schlüssel tragen. Ein Gerät koppelt deshalb weiterhin eine Person, die im Portal angemeldet ist.

Schritte

  1. Suchen Sie den Standort. GET /v1/locations liefert alle Standorte Ihrer Organisation in einer Antwort, ohne Blättern:

    GET/v1/locations
    curl -sS "$SZENERA_API/v1/locations" \  -H "Authorization: Bearer $SZENERA_API_KEY" \  | jq -r '.locations[] | "\(.id)  \(.name)"'
    loc_01KFB7QPW0LOCATION00000001  Filiale Nord

  2. Legen Sie das Display an. Name und Standort genügen. Der Idempotenz-Schlüssel macht eine Wiederholung nach einem Verbindungsabbruch sicher, es entsteht also nie versehentlich ein zweites Display:

    POST/v1/web-displays
    curl -sS -X POST "$SZENERA_API/v1/web-displays" \  -H "Authorization: Bearer $SZENERA_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: rollout-filiale-nord-theke" \  -d '{ "name": "Filiale Nord Theke", "locationId": "loc_01KFB7QPW0LOCATION00000001" }'
    Antwort
    {  "playerId": "ply_01KFB7QPW0PLAYER0000000001",  "token": "drc_01KFB7QPW0TOKEN00000000001",  "connectUrl": "https://webplayer.szenera.com/?reconnect=drc_01KFB7QPW0TOKEN00000000001",  "expiresAt": "2026-09-11T10:00:00.000Z"}

    Das Display gibt es sofort. Es belegt einen gebuchten Platz und steht als Nicht verbunden in der Flotte, bis ein Browser connectUrl öffnet.

  3. Weisen Sie das Programm zu. Öffnen Sie das Programm im Portal: Die Adresse endet mit seiner Kennung sch_…. Eine Szene (scene, sceneId), eine Playlist (playlist, playlistId) oder ein einzelnes Medium (media, assetId) geht genauso:

    PUT/v1/players/ply_01KFB7QPW0PLAYER0000000001/program
    curl -sS -X PUT "$SZENERA_API/v1/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 egal. Ein Display, das schon vor dem Anschließen ein Programm hat, zeigt es, sobald der Browser da ist.

  4. Geben Sie die Adresse weiter. Schicken Sie connectUrl an die Person am Fernseher, zum Beispiel per E-Mail. Sie gilt einmal und läuft nach 24 Stunden ab. Wer sie im Browser des Fernsehers öffnet, bindet diesen Browser an das Display.

Der ganze Rollout als Skript

Das Skript liest eine CSV-Datei mit Kopfzeile und den Spalten Name und Standort, legt je Zeile ein Display an, gibt allen dasselbe Programm und schreibt Name und Adresse jedes Displays aus:

Für viele gleiche Displays an einem Standort legt POST /v1/web-displays/batch bis zu 50 mit nummerierten Namen in einem Aufruf an, ganz oder gar nicht. Die Routen der Web-Displays tragen x-stability: beta, siehe Web-Displays.

name,locationFiliale Nord Theke,Filiale NordFiliale Nord Schaufenster,Filiale NordFiliale Süd Theke,Filiale Süd
TypeScript
// rollout.ts: node rollout.ts displays.csvimport { readFile } from 'node:fs/promises'; const API = process.env.SZENERA_API;const KEY = process.env.SZENERA_API_KEY;const PROGRAM = process.env.SZENERA_PROGRAM_ID; // sch_… async function call(method: string, path: string, body?: unknown, idempotencyKey?: string) {  const headers: Record<string, string> = {    Authorization: `Bearer ${KEY}`,    'Content-Type': 'application/json',  };  if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;  const res = await fetch(`${API}${path}`, {    method,    headers,    body: body === undefined ? undefined : JSON.stringify(body),  });  if (!res.ok) throw new Error(`${method} ${path}: ${res.status} ${await res.text()}`);  return res.json();} const { locations } = await call('GET', '/v1/locations');const locationIds = new Map(locations.map((location) => [location.name, location.id])); const rows = (await readFile(process.argv[2], 'utf8')).trim().split('\n').slice(1);for (const row of rows) {  const [name, locationName] = row.split(',').map((cell) => cell.trim());  const locationId = locationIds.get(locationName);  if (!locationId) throw new Error(`Unknown location: ${locationName}`);   // Gleicher Name, gleicher Schlüssel: Ein zweiter Lauf binnen 24 Stunden legt nichts doppelt an  const display = await call(    'POST',    '/v1/web-displays',    { name, locationId },    `rollout-${encodeURIComponent(name)}`,  );  await call('PUT', `/v1/players/${display.playerId}/program`, {    program: { kind: 'schedule', scheduleId: PROGRAM },  });  console.log(`${name}\t${display.connectUrl}`);}

Ergebnis prüfen

  • Das Display steht mit Namen, Standort und dem Zustand Nicht verbunden in der Flotte.
  • GET /v1/players/{id}/program nennt das zugewiesene Programm.
  • Sobald der Browser des Fernsehers die Adresse geöffnet hat, wechselt der Zustand auf Online, und das Programm läuft.

Wenn etwas nicht klappt

Symptom Bedeutung Lösung
402 Billing.LicensesExhausted Alle gebuchten Plätze sind belegt. Die Antwort nennt booked und used. Plätze dazubuchen oder Displays löschen, die Sie nicht mehr brauchen.
403 Billing.FeatureNotEntitled Die Fähigkeit Displays ohne Agent ist für Ihre Organisation abgeschaltet. Beim Betreiber der Plattform freischalten lassen.
403 Permission.Denied Dem Schlüssel fehlt eines der drei Rechte. Einen Schlüssel der Klasse Individuell mit genau diesen Rechten erzeugen.
404 Location.NotFound Die Standort-Kennung gehört nicht zu Ihrer Organisation. Die Kennung aus GET /v1/locations nehmen.
422 Schedule.ContentNotFound Programm, Szene, Playlist oder Medium gibt es nicht. Die Kennung in der Portal-Adresse prüfen.
Die Adresse führt zu einem Kopplungscode Die Adresse war schon benutzt oder ist abgelaufen. Mit POST /v1/web-displays/{id}/link eine neue ausstellen und diese öffnen.

Weiterführendes

3 Min LesezeitStand 30. Okt. 2026Als Markdown

War das hilfreich?