Ereignistypen: Inhalte, Programme, Geräte, Apps

Die abonnierbaren Ereignistypen aus Medien, Szenen, Programmen, Marktplatz, Flotte, App-Laufzeit, Wiedergabe, Auswertung und Werbung — die Ereignisse, mit denen die meisten Anbindungen beginnen.

So lesen Sie die Tabellen#

• Ereignistyp ist die Zeichenkette, die Sie beim Endpunkt abonnieren. Sie kommt bei jeder Zustellung in der Kopfzeile X-Event-Type an. Statt einzelner Typen dürfen Sie auch einen ganzen Bereich abonnieren (composition.*) oder mit * alles. Mehr Formen gibt es nicht, und alles andere weist der Server ab, siehe Den Ereigniskatalog über die API abrufen.
• Nutzlast-Kern nennt zwei bis vier der wichtigsten Felder, die im Rumpf der Zustellung stehen. Es ist ein Auszug. Die vollständige Form bestimmt der jeweilige Bereich, und sie kann weitere Felder tragen. Zeitpunkt, Ereigniskennung und Auslöser reisen nicht im Rumpf.
• Wann es entsteht ist ein Halbsatz zur Einordnung, keine Aussage über Häufigkeit.

Das Portal bietet unter Abonnierte Ereignisse genau die Typen dieser Seite und der Seite Ereignistypen: Organisation, Konten, Abrechnung zur Auswahl — dieselbe Liste, die GET /v1/webhooks/event-types liefert. Alles andere lässt sich nicht abonnieren, das Anlegen eines Endpunkts weist es ab. Welche Typen das sind, steht unter Was nie ankommt. Zugestellt wird nur, was im Kontext Ihrer Organisation entsteht.

In den Feldern bezeichnet playerId ein Display (Kennung ply_…) und deviceId das Gerät, an dem es hängt.

Die Ereignistypen#

Medien#

Dateien vom Upload bis zur fertigen Aufbereitung, Ordner und automatische Sammlungen. asset.ready schließt die Aufbereitung der Varianten ab, asset.deleted stößt die Prüfung der Szenen an, die die Datei nutzen.

Szenen und Vorlagen#

Szenen, ihre Versionen und Layout-Vorlagen. scene-version.created ist der Auslöser, an dem Wiedergabe und Programme nachziehen.

Playlisten und Programme#

Playlisten, Programme, die Zuweisung an Displays und die Planfassungen. schedule-item.changed und player-program.changed sind bewusst je ein Sammel-Ereignis mit action-Feld. timeline.invalidated nennt in reason den Anlass: timeline-invalidated oder media-source-changed (die Medien-Auswahl einer automatischen Playlist hat sich verschoben). plan-revision.recorded hält den Plan eines Displays für die nächsten 48 Stunden fest. Aus ihm rechnen Auswertung und Werbung die Planzeit und das Soll kommender Stunden.

Marktplatz: installierte Apps#

Apps aus Sicht Ihrer Organisation: Installation, Aktualisierung, Zustimmung und Ablehnung, die Bitten an die Inhaber, die Umstellung am Ende einer Auslauffrist, die Deinstallation und die Löschung der App-Daten danach.

Flotte: Geräte, Displays, Standorte, Leinwände#

Geräte, Displays, Befehle, Schlagwörter, Leinwände, Standorte und Systemaktualisierungen. Es gibt kein Ereignis je Lebenszeichen — player.status-changed ist die Spur für online und offline. Die display-group.*-Ereignisse sind die Leinwände, ihr memberPlayerIds nennt die betroffenen Displays. Die ota-*-Ereignisse tragen die Geräte-Kennung (deviceId), weil ein Systemstand am Gerät hängt, nicht am einzelnen Display.

App-Laufzeit#

Datenabrufe und wiederkehrende Jobs installierter Apps. fetch.completed ist der Auslöser, an dem die Wiedergabe neue App-Daten übernimmt.

Wiedergabe#

Der berechnete Wiedergabestand je Display und die Meldungen der Wiedergabe-Software. Protokolliert wird hier nur, was schiefgeht. Die übrigen Ereignisse sind Maschinenverkehr, dessen Menge mit der Zahl der Displays wächst.

Auswertung#

Verdichtete Messwerte, Kennzahlen, Berichte, Nachweise und die Verweise für Werbepartner. analytics.proof.issued erreicht Ihren Endpunkt für jeden Nachweis Ihres Direktgeschäfts: für Abschlüsse und Nachträge aus dem nächtlichen Lauf ebenso wie für einen Zwischenstand, den Ihre Organisation anfordert. Nachweise des Werbenetzes gehören keiner Organisation und erreichen keinen Endpunkt.

Werbung#

Werbepartner, Werbekampagnen mit ihren Buchungen, Motive und ihre Freigabe, die Werbefläche der Displays, das Publikum der Standorte, die Teilnahme am Werbenetz und die Gutschrift über die Werbeerlöse eines Monats. Die Ereignisse sind schmal, den Stand dazu lesen Sie unter /v1/advertising/… nach. Die Ereignisse zu Werbepartnern, Werbekampagnen, Buchungen und Motiven nennen in ownerKind und tenantId, wem die Zeile gehört. Zugestellt werden nur die Zeilen Ihrer Organisation (ownerKind: tenant). Werbepartner, Werbekampagnen, Buchungen und Motive des Werbenetzes tragen keine Organisation und erreichen keinen Endpunkt.

Was nie ankommt#

Der Katalog unter GET /v1/webhooks/event-types führt 241 der 338 Ereignistypen der Plattform, in 16 Bereichen — genau die Typen dieser Seite und der Seite Ereignistypen: Organisation, Konten, Abrechnung. Die übrigen 97 sind nicht abonnierbar: die Ereignisse der Zustellung selbst und alles, was ohne Bezug zu einer Organisation entsteht. Das Anlegen und Ändern eines Endpunkts weist solche Typen mit 422 WebhookEndpoint.EventUnknown ab, und ein Bereichs-Abo wie ops.* gibt es für diese Bereiche nicht. Das sind:

• Die Ereignisse der Zustellung selbst. Die zwölf Typen unter notifications.* — In-App-Nachrichten, E-Mail-Versand und die Webhook-Verwaltung (notifications.webhook.endpoint.created, .endpoint.disabled, .webhook.delivered, .failed, .dead) — lösen nie einen Webhook aus, sonst löste jede Zustellung die nächste aus. Die Abschaltung eines Endpunkts sehen Sie im Portal am Status Inaktiv, nicht per Webhook.
• Ereignisse des Plattformbetriebs. Die 16 Typen unter ops.* (Wartungsfenster, Störungen, Systemzustand, Gerätesoftware) entstehen ohne Bezug zu einer Organisation.
• Der App-Katalog. Die acht Typen unter app-catalog.* (Fassungen, Pakete und Status der Apps im Katalog): Eine Fassung wird einmal für die Plattform veröffentlicht, nicht je Organisation. Was daraus bei Ihnen folgt, melden die marketplace.app.*-Ereignisse.
• Geräte, bevor sie einer Organisation gehören, und die Technik der Verbindung. fleet.pairing.code-issued und fleet.pairing.code-rotated (Kopplungscodes entstehen vor der Zuordnung), identity.device.unblocked (der Betreiber hebt eine Sperre an einem Gerät auf, das keiner Organisation mehr gehört), device.ota.available und device.software.available (der Anstoß einer Aktualisierung durch den Betreiber) sowie die vier Typen unter realtime.* (Verbindungen und Lebenszeichen, Dauerverkehr).
• Konten und Schlüssel des Betreibers. Die acht Typen unter identity.operator-user.* und die drei unter identity.operator-api-key.*, verwaltet in der Betreiber-Oberfläche.
• Die Stellgrößen des Werbenetzes. advertising.network-parameters.changed: Der Betreiber setzt sie für das ganze Netz, sie gehören keiner Organisation. Ein Bereichs-Abo wie advertising.* schließt sie nicht ein.
• Die Plattformschicht. 27 Typen unter auth.*, permissions.*, outbox.*, audit.*, jobs.* und apps.* (Schlüsselwechsel, Warteschlangen, Änderungsprotokoll, Start der Apps) sowie feeds.source.updated (der Feed-Katalog gehört der Plattform). Auch die Typen des Änderungsprotokolls gehören dazu: audit.export.requested, audit.export.completed und audit.pseudonymization.completed sind nicht abonnierbar.

Auch ein Typ aus dem Katalog erreicht Ihren Endpunkt nur, wenn der Vorgang im Kontext Ihrer Organisation entsteht. Vorgänge des Plattformbetriebs (in den Tabellen so vermerkt) und die Zeilen des Werbenetzes tragen keine Organisation. Sie bleiben aus, ohne Fehlversuch und ohne Eintrag im Zustellprotokoll.

Womit Sie anfangen können#

Vier Abonnements, mit denen sich die meisten Anbindungen prüfen lassen, weil Sie sie im Portal selbst auslösen: composition.scene.published (eine Szene veröffentlichen), scheduling.playlist.updated (eine Playlist ändern), media-library.asset.ready (eine Datei hochladen) und fleet.player.status-changed (ein Display vom Netz trennen).

Weiterführendes#

• Ereignistypen: Organisation, Konten, Abrechnung
• Einen Webhook-Endpunkt anlegen