Notifications : commandes CLI

Opérations

Les téléversements et les publications s’exécutent comme des opérations. media upload, media replace et app upload attendent la leur par défaut ; ces commandes servent à terminer une opération laissée en cours avec --no-wait.

operations show <id>

screenrig operations show op_01EXAMPLEOPERATION00000

operations wait <id> [--timeout MS] [--poll-ms MS]

screenrig operations wait op_01EXAMPLEOPERATION00000

operations cancel <id>

screenrig operations cancel op_01EXAMPLEOPERATION00000

Événements

Le journal d’événements du projet enregistre ce que le projet a fait et ce que la flotte a fait. Une version publiée ajoute application.published ; une application qui appelle screenrig.emit(code) ajoute son propre événement, qui est la preuve la plus directe qu’elle a été exécutée sur un écran.

La présence est aussi dans le journal. screen.offline est écrit une fois qu’un écran est hors ligne depuis 60 secondes, et screen.online quand il revient ; une reconnexion dans ces 60 secondes n’écrit ni l’un ni l’autre. screen.offline porte details.offline_since et, quand l’écran a déjà été en ligne, details.last_online_at. screen.online porte details.last_online_at, plus details.offline_at quand l’écran était hors ligne avant de revenir. Comme chaque événement screen.*, ils sont gratuits sur le flux d’écoute, donc un agent peut garder events follow ouvert pour surveiller une flotte.

Les mises à jour de contenu d’un Player arrivent sous forme de screen.manifest_changed, screen.manifest_activated et screen.manifest_upgrade, dont les details portent manifest_revision, state et, lorsqu’ils sont présents, code et attempt. Une mise à niveau failed a la gravité d’erreur, et retrying, blocked et partial sont des avertissements.

events list [--after CURSOR] [--limit N] [--type TYPE] [--source project|log] [--screen-id ID] [--playlist-id ID] [--app-id ID]

screenrig events list --limit 25
screenrig events list --type application.event --screen-id scr_SCREEN
screenrig events list --playlist-id pl_PLAYLIST
screenrig events list --source log --screen-id scr_SCREEN

events follow [--after CURSOR] [--timeout MS] [--type TYPE]

screenrig events follow

Notifications

Une notification avertit une personne, ou un autre système, lorsqu’un écran change d’état. Une notification par courriel envoie un courriel à chaque destinataire, une notification webhook envoie un POST HTTPS signé, et une notification Slack, Teams, PagerDuty ou Telegram publie un message dans une messagerie ou un outil d’alerte. Une organisation en compte au plus 50, tous canaux confondus et tous projets confondus, et chaque projet démarre avec un courriel à son propriétaire lorsqu’un écran est hors ligne depuis 10 minutes.

Une notification surveille les conditions que vous nommez :

Une condition déclenche un avis une fois qu’elle a duré --hold minutes (10 par défaut), donc une reconnexion rapide reste silencieuse. Si elle prend fin avant, rien n’est envoyé ; si elle prend fin après l’envoi d’un avis, un avis de résolution suit. crashing est envoyé immédiatement. Un avis est aussi ignoré lorsque quelqu’un acquitte ou reporte l’alerte de l’écran pendant le délai d’attente, ou lorsqu’une mise en sourdine couvre l’écran. --tag limite une notification aux écrans portant cette étiquette ; sans étiquette, tous les écrans comptent.

Chaque avis a une gravité. Un avis ouvert est error pour screen_offline et warning pour toute autre condition, et un avis résolu ou un test est info. --min-severity LEVEL (info, warning ou error) ne crée aucun avis ouvert sous ce niveau, et un avis résolu suit son avis ouvert. --severity CONDITION=LEVEL, répétable, définit le niveau d’une condition pour cette notification, comme --severity not_playing=error ; il compte pour --min-severity. Teams et PagerDuty affichent toujours le niveau, le texte des courriels, de Slack et de Telegram le nomme quand la notification définit --min-severity ou --severity, et le corps d’un webhook porte severity.

--active-hours SPEC envoie les avis ouverts seulement à l’intérieur de fenêtres hebdomadaires, lues dans --timezone ZONE, qu’il exige. SPEC est DAYS HH:MM-HH:MM, comme "Mon-Fri 08:00-22:00" ; répétez-le jusqu’à 16 fois. Avec --outside-hours hold, la valeur par défaut, un avis qui arrive à échéance en dehors des heures attend la prochaine fenêtre et part alors si sa condition tient toujours, de sorte qu’une condition qui disparaît d’abord n’envoie rien. Avec drop, l’avis est ignoré comme outside_hours, que notifications deliveries liste. Un avis résolu pour un avis ouvert qui a été envoyé part toujours, crashing suit les heures comme n’importe quelle autre condition, un report est vérifié en premier, et notifications test ignore les heures, la gravité et l’audience.

--audience FILE (JSON en ligne, un fichier ou - pour l’entrée standard) choisit les écrans selon les règles d’une audience de campagne, comme {"all":[{"tag":"level2"},{"tag":"overhead"}]} pour les écrans portant les deux étiquettes ; --all-tags TAG et --any-tag TAG sont les raccourcis pour une règle all et une règle any d’étiquettes, et --tag signifie n’importe laquelle des étiquettes. --tag, --any-tag, --all-tags et --audience s’excluent mutuellement.

loop_stalled, glass_blank et glass_frozen sont des verdicts que screenRIG tire des rapports de lecture et des captures d’écran qu’il reçoit, et ils laissent de côté ce qu’ils ne peuvent pas juger : un écran hors ligne, dont l’affichage est éteint, sous prise de contrôle ou suspendu, qui montre une seule image fixe ou un mur vidéo, ou dont le Player n’envoie pas de numéros de lecture. Lorsque screenRIG cesse de juger un écran qu’il avait trouvé dans l’un de ces états, l’alerte se ferme, mais le courriel, Slack, Teams et Telegram n’envoient aucun avis de résolution, car rien n’a montré que l’écran se rétablissait ; PagerDuty résout tout de même son incident.

source_failed et source_stale surveillent les sources de données du projet, pas ses écrans : un avis nomme la source et renvoie à sa page, et --tag ne correspond jamais à une source.

card_data_stale surveille une carte, pas un écran. Écrivez les données d’une carte avec une expiration adaptée au calendrier de son rédacteur (card data put --ttl 30m) : quand la tâche ou l’agent qui les renouvelle s’arrête, les données expirent, la carte est vide sur chaque écran qui l’affiche, et cette condition vous en informe. L’avis nomme la carte et le moment où ses données ont expiré, et renvoie à l’éditeur de pages sur une page qui la place. Les documents d’une source de données ne sont jamais annoncés ici (source_stale s’en charge), pas plus qu’une carte qu’aucun écran n’affiche, des données écrites sans expiration ou des données supprimées. --tag ne correspond jamais à une carte.

reach_dropped et group_empty surveillent une campagne, pas un écran. L’avis nomme la campagne et les écrans qu’elle atteignait avant et atteint maintenant, ou l’étiquette ou le dossier vide, et renvoie au calendrier de la campagne. Une campagne appartient au projet, donc --tag, --any-tag, --all-tags et --audience ne les limitent jamais ; --min-severity, --severity, --active-hours et --hold s’appliquent comme pour toute condition, et les deux sont warning par défaut. --reach-drop-screens N et --reach-drop-percent P n’envoient un avis reach_dropped que pour une baisse d’au moins N écrans et d’au moins P pour cent des écrans que la campagne atteignait lors de sa publication ; une baisse doit remplir les deux seuils, et sans eux toute baisse déclenche un avis. Ils exigent reach_dropped dans --conditions. Chaque étiquette ou dossier vide d’une campagne donne son propre avis, et notifications deliveries l’affiche comme audience_group (tag:Lobby ou folder:sfd_…). Une publication qui retire un groupe vide de l’audience ferme un incident PagerDuty et l’alerte d’un webhook, mais n’envoie aucun courriel ni message de rétablissement dans une messagerie.

Le courriel est envoyé à l’adresse vérifiée de chaque destinataire, un courriel par destinataire pour tout ce qui arrive à échéance en l’espace d’environ deux minutes, avec un lien vers chaque écran et vers la notification dans le tableau de bord. Les destinataires sont owner (la personne qui possède le projet au moment de l’envoi de l’avis) et les identifiants d’utilisateur des membres du projet. Un destinataire sans adresse vérifiée, ou qui a quitté le projet, est ignoré. Les courriels de notification et les avis d’écran sont gratuits.

Chaque courriel contient un lien de désabonnement pour son propre destinataire : le bouton de désabonnement des applications de courriel et un lien dans le pied de page. Le suivre arrête les courriels de cette notification pour cette seule personne, sans connexion, et la page qui s’ouvre contient un bouton Resubscribe. Les autres destinataires ne sont pas touchés, et la personne reste parmi les destinataires. notifications show indique qui s’est désabonné avec unsubscribed, et notifications resubscribe lui renvoie des courriels. Un avis sans personne à qui écrire est ignoré avec no_recipients.

Une notification par webhook envoie chaque avis par POST en JSON, et vous le vérifiez comme décrit dans Vérifier une livraison. Avec --events, elle envoie aussi par POST les événements bruts du projet au fur et à mesure ; ces livraisons sont mesurées comme décrit dans Webhooks.

Une notification Slack, Teams, PagerDuty ou Telegram publie un message par panne et par écran, ou par groupe d’écrans : l'écran, ce qui a changé, depuis quand, le projet, un lien vers l'écran et, lorsqu'un écran hors ligne revient, sa cause probable si elle est connue à ce moment-là. Un message de rétablissement suit une fois le premier envoyé et, dans PagerDuty, il résout l'incident ouvert par le premier. Vous donnez le justificatif une seule fois (--slack prend l'URL d'un webhook entrant, --teams l'URL d'un webhook Workflows, --pagerduty une clé d'acheminement de l'API Events v2, --telegram un jeton de bot avec --telegram-chat); il est scellé, jamais affiché de nouveau, et destination_hint n'en montre que la fin masquée. Un - le lit depuis une ligne de stdin pour qu'il reste hors de l'historique de votre shell. Une publication échouée est retentée pendant 24 heures, et une notification qui échoue pendant 72 heures est désactivée.

Quand trois écrans ou plus entrent dans la même condition à moins de cinq minutes les uns des autres et partagent un réseau, un emplacement, un modèle, une version du Player ou une étiquette, une notification par courriel, Slack, Teams, PagerDuty ou Telegram envoie un seul avis pour eux au lieu d’un par écran, et un seul avis annonce le groupe quand son dernier écran est rétabli ; l’avis de chaque autre écran est ignoré comme grouped. Un webhook envoie toujours un avis par écran.

La lecture des notifications et de leurs livraisons demande l’accès Lecture seule ; créer, modifier, tester et supprimer une notification, renouveler son secret et réabonner une personne demandent l’accès Gérer.

notifications create (--email RECIPIENTS | --webhook URL | --slack URL | --teams URL | --pagerduty KEY
                      | --telegram TOKEN --telegram-chat CHAT_ID) [--conditions LIST] [--events TYPES]
                     [--tag TAG... | --any-tag TAG... | --all-tags TAG... | --audience FILE] [--hold MINUTES]
                     [--min-severity LEVEL] [--severity CONDITION=LEVEL]... [--active-hours SPEC]...
                     [--timezone ZONE] [--outside-hours hold|drop] [--reach-drop-screens N] [--reach-drop-percent P]
                     [--description TEXT] [--disabled]

screenrig notifications create --email owner --conditions screen_offline,display_disconnected --tag Lobby

screenrig notifications create --webhook https://hooks.example.com/screenrig --conditions screen_offline,crashing

screenrig notifications create --slack - --conditions screen_offline,crashing < slack-url.txt

notifications list

screenrig notifications list

notifications show <id>

screenrig notifications show ntf_01EXAMPLENOTICE00000

notifications update <id> [--email RECIPIENTS | --url URL | --destination VALUE] [--telegram-chat CHAT_ID]
                          [--conditions LIST | --clear-conditions]
                          [--events TYPES | --clear-events] [--tag TAG... | --any-tag TAG... | --all-tags TAG... | --audience FILE | --all-screens]
                          [--hold MINUTES] [--min-severity LEVEL | --clear-min-severity]
                          [--severity CONDITION=LEVEL]... [--clear-severity]
                          [--active-hours SPEC]... [--timezone ZONE] [--outside-hours hold|drop] [--clear-active-hours]
                          [--reach-drop-screens N] [--reach-drop-percent P] [--clear-reach-drop]
                          [--description TEXT | --clear-description] [--enable | --disable]
                          [--snooze WHEN] [--expect-rev REVISION]

screenrig notifications update ntf_01EXAMPLENOTICE00000 --snooze 2h

notifications delete <id> [--expect-rev REVISION]

screenrig notifications delete ntf_01EXAMPLENOTICE00000

notifications rotate-secret <id> [--expect-rev REVISION]

screenrig notifications rotate-secret whk_01EXAMPLEWEBHOOK00000

notifications test <id>

screenrig notifications test ntf_01EXAMPLENOTICE00000

notifications resubscribe <id> --user USER_ID

screenrig notifications resubscribe ntf_01EXAMPLENOTICE00000 --user usr_01EXAMPLEPERSON0000

notifications deliveries <id> [--before CURSOR] [--limit N]

screenrig notifications deliveries ntf_01EXAMPLENOTICE00000 --limit 20

Vérifier une livraison

Le corps d’un avis d’écran est du JSON : type (alert.opened ou alert.resolved), id (l’identifiant de livraison), notification_id, project_id, condition, screen (id et name), since (quand la condition a commencé), at (quand elle a duré assez longtemps, ou quand elle a pris fin), event_id et severity (info, warning ou error : le niveau de la condition pour alert.opened, info pour alert.resolved). alert.resolved pour screen_offline porte aussi likely_cause (device_restart, app_crash, app_restart, network ou platform), null tant que la cause est inconnue. Pour une source de données, une campagne ou une carte, screen la désigne, et un avis de campagne ajoute reach (published et current écrans) pour reach_dropped ou audience_group (kind tag ou folder, et value) pour group_empty. Un événement brut issu de --events est le même objet JSON que events list renvoie. Les en-têtes sont ScreenRig-Webhook-Id (l’identifiant de la notification), ScreenRig-Event-Id (stable entre tentatives : l’identifiant de livraison pour un avis, le curseur d’événement pour un événement), et ScreenRig-Signature: t=<unix seconds>,v1=<hex>, où v1 est un HMAC-SHA256 sur "<t>.<raw body>" avec la chaîne secrète. Calculez-le sur les octets bruts avant d’analyser le JSON, comparez en temps constant, rejetez un ancien t, et dédupliquez sur ScreenRig-Event-Id, car la livraison est au moins une fois et non ordonnée. Répondez 2xx dans les 10 secondes ; les redirections ne sont pas suivies.

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body bytes (Buffer) exactly as received.
function verify(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
  if (typeof signatureHeader !== "string" || !signatureHeader) return false;
  const parts = Object.fromEntries(signatureHeader.split(",").map((part) => part.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Alertes

Une alerte est un problème sur un écran, tant qu’il dure. Elle s’ouvre lorsqu’un écran entre dans l’une des conditions de notification d’écran (screen_offline, display_disconnected, running_hot, on_battery, storage_full, content_stuck, not_playing, loop_stalled, glass_blank ou glass_frozen), qu’une notification la surveille ou non, et se résout lorsque la condition prend fin. Un écran a au plus une alerte ouverte par condition. Un pic de plantages, une source de données, une carte et une campagne sont des avis, jamais des alertes. Un écran qui redémarre pour un redémarrage envoyé par screenRIG (screen reboot ou une planification de redémarrage) n’ouvre aucune alerte screen_offline ou display_disconnected jusqu’à la fin du redémarrage ou jusqu’à dix minutes après son envoi ; une condition qui persiste alors ouvre son alerte. alerts list montre ce qui est ouvert maintenant.

Une alerte ouverte demande de l’attention jusqu’à ce que quelqu’un l’acquitte ou la reporte, ou qu’une mise en sourdine couvre son écran. Acquitter signifie que quelqu’un s’en occupe : l’alerte reste ouverte, enregistre qui l’a acquittée et quand, et ne demande plus d’attention jusqu’à sa résolution. Reporter acquitte jusqu’à un moment au plus 30 jours plus tard, et l’alerte demande de nouveau de l’attention à ce moment si elle est encore ouverte. Un acquittement ou un report ultérieur remplace le précédent. Tant qu’une alerte est acquittée ou reportée, l’avis d’une notification à son sujet qui est encore en délai d’attente est ignoré.

Une mise en sourdine sert à la maintenance : elle nomme des écrans, des étiquettes ou les deux, et prend fin à un moment au plus 30 jours plus tard. Elle couvre un écran tant que son identifiant est listé ou qu’il porte une étiquette listée ; un écran étiqueté plus tard est donc couvert, et un écran qui perd l’étiquette ne l’est plus. Les alertes d’un écran en sourdine s’ouvrent et se résolvent toujours, marquées muted, mais n’exigent jamais d’attention, et chaque notification ignore leurs avis. Une organisation compte au plus 50 mises en sourdine en cours, tous projets confondus.

counts.attention dans alerts list est le nombre que le tableau de bord affiche à côté d’Alertes. L’ouverture, la résolution et l’acquittement d’une alerte ajoutent screen.alert_opened, screen.alert_resolved et screen.alert_acknowledged au journal des événements du projet, et la création et la fin d’une mise en sourdine ajoutent alert_mute.created et alert_mute.deleted. Ils sont gratuits sur le flux d’écoute et sur les webhooks, comme tout événement screen.*. Les alertes résolues restent listées pendant la rétention d’événements du forfait. La lecture des alertes et des mises en sourdine demande l’accès Lecture seule ; acquitter, reporter, mettre en sourdine et lever une mise en sourdine demandent l’accès Gérer.

alerts list [--state open|resolved|all] [--screen-id ID] [--before CURSOR] [--limit N]
            [--format json|csv|xlsx|pdf] [--output FILE]

screenrig alerts list

screenrig alerts list --state all --screen-id scr_01EXAMPLESCREEN00000000

screenrig alerts list --state all --format csv --output alerts.csv

alerts show <id>

screenrig alerts show alr_01EXAMPLEALERT000000

alerts ack <id>

screenrig alerts ack alr_01EXAMPLEALERT000000

alerts snooze <id> (--for DURATION | --until TIME)

screenrig alerts snooze alr_01EXAMPLEALERT000000 --for 4h

alerts mute [--screen-id ID]... [--tag TAG]... (--for DURATION | --until TIME) [--note TEXT]

screenrig alerts mute --tag Lobby --for 2h --note "Rewiring the lobby displays"

alerts mutes

screenrig alerts mutes

alerts unmute <mute-id>

screenrig alerts unmute amt_01EXAMPLEMUTE0000000

Webhooks

Un webhook envoie les événements propres à ce projet, sous forme de POST signés, vers un point de terminaison HTTPS que vous exécutez, ainsi un événement correspondant peut réveiller un agent, un bot ou votre propre service. Chaque événement correspondant arrive comme le même objet JSON que events list renvoie. Un webhook est une notification sous sa forme d’origine : il compte parmi les 50 notifications de l’organisation, et notifications list l’affiche. Tout nouveau travail utilise notifications, qui envoie aussi des courriels et des avis d’écran.

Chaque tentative d’envoi est gratuite et ne compte pas dans la limite horaire de requêtes d’agent de l’organisation.

webhooks create --url URL --event-types TYPES [--description TEXT] [--disabled]
webhooks list
webhooks show <id>
webhooks update <id> [--url URL] [--event-types TYPES] [--description TEXT | --clear-description]
                     [--enable | --disable] [--expect-rev REVISION]
webhooks delete <id> [--expect-rev REVISION]
webhooks rotate-secret <id> [--expect-rev REVISION]
webhooks test <id>
webhooks deliveries <id> [--before CURSOR] [--limit N]

webhooks create répond webhook_limit_reached (sortie 5) lorsque l’organisation compte déjà 50 notifications, alors que notifications create répond notification_limit_reached. Une URL refusée donne webhook_url_rejected (sortie 8) dans les deux cas.

--url prend une URL https sur le port 443 ou 8443 dont l’hôte ne résout qu’en adresses Internet publiques, vérifiée comme pour notifications create ; une URL qui contient des identifiants ou un fragment # est refusée localement avec la sortie 2. --event-types prend de 1 à 32 types exacts séparés par des virgules, comme screen.online, ou des préfixes se terminant par .*, comme screen.*. --description fait au plus 200 caractères. --disabled crée le webhook désactivé. webhooks update --enable efface l’état d’échec et repart de l’événement courant, de sorte que rien de ce qui s’est passé pendant sa désactivation n’est envoyé, et --disable fait échouer les livraisons en attente avec webhook_disabled. --expect-rev contrôle la révision (revision_conflict, sortie 6).

webhooks create et webhooks rotate-secret affichent une seule fois le secret de signature dans data.secret avec l’avertissement webhook_secret_shown_once ; après un appel interrompu ou ambigu, relancez la même commande dans les 24 heures pour récupérer la même réponse. La livraison commence au premier événement qui suit la création du webhook. webhooks test met en file une livraison webhook.test pour ce webhook uniquement ; elle fonctionne sur un webhook désactivé, n’est tentée qu’une fois sans nouvelle tentative, est mesurée comme toute livraison et est limitée à 20 par minute et par organisation (rate_limited, sortie 7). webhooks list liste les notifications webhook de ce projet, des plus anciennes aux plus récentes, et un identifiant en lecture seule reçoit chaque url vide avec url_redacted à true. webhooks deliveries lit le journal en commençant par l’événement le plus récent, de 1 à 200 lignes par page (50 par défaut), avec next_cursor (whc1_…) comme --before ; le state d’une ligne est pending, succeeded ou failed, avec last_status et une classe last_error fixe. Vérifiez une livraison comme décrit sous Vérifier une livraison.