Notifiche: comandi CLI

Operazioni

I caricamenti e le pubblicazioni vengono eseguiti come operazioni. media upload, media replace e app upload attendono la propria per impostazione predefinita; questi comandi servono a concludere un’operazione lasciata in esecuzione con --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

Eventi

Il registro eventi del progetto registra cosa ha fatto il progetto e cosa ha fatto la flotta. Un rilascio pubblicato aggiunge application.published; un’app che chiama screenrig.emit(code) aggiunge il proprio evento, che è la prova più diretta che è stata eseguita su uno schermo.

La presenza è anche nel log. screen.offline è scritto una volta che uno schermo è offline da 60 secondi, e screen.online quando torna online; una riconnessione entro quei 60 secondi non scrive nulla. screen.offline contiene details.offline_since e, quando lo schermo è stato online prima, details.last_online_at. screen.online contiene details.last_online_at, più details.offline_at quando lo schermo era offline prima di tornare. Come ogni evento screen.*, sono gratuiti sul flusso di ascolto, così un agente può mantenere events follow aperto per osservare una flotta.

Gli aggiornamenti dei contenuti di un Player arrivano come screen.manifest_changed, screen.manifest_activated e screen.manifest_upgrade, i cui details riportano manifest_revision, state e, se presenti, code e attempt. Un aggiornamento failed ha gravità di errore, e retrying, blocked e partial sono avvisi.

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

Notifiche

Una notifica avvisa una persona, o un altro sistema, quando uno schermo cambia stato. Una notifica e-mail invia un’e-mail a ogni destinatario, una notifica webhook invia un POST HTTPS firmato e una notifica Slack, Teams, PagerDuty o Telegram pubblica un messaggio in una chat o in un sistema di reperibilità. Un’organizzazione ne ha al massimo 50, tutti i canali e tutti i suoi progetti insieme, e ogni progetto parte con un’e-mail al proprietario quando uno schermo è offline da 10 minuti.

Una notifica monitora le condizioni che indichi:

Una condizione invia un avviso quando dura da --hold minuti (predefinito 10), così una riconnessione rapida resta silenziosa. Se termina prima, non viene inviato nulla; se termina dopo l’invio di un avviso, segue un avviso di risoluzione. Per crashing l’avviso viene inviato subito. Un avviso viene saltato anche quando qualcuno riconosce o posticipa l’alert dello schermo durante il tempo di attesa, o quando un silenziamento copre lo schermo. --tag limita una notifica agli schermi con quel tag; senza, vengono considerati tutti gli schermi.

Ogni avviso ha una gravità. Un avviso aperto è error per screen_offline e warning per ogni altra condizione, e un avviso risolto o un test è info. --min-severity LEVEL (info, warning o error) non crea alcun avviso aperto sotto quel livello, e un avviso risolto segue quello aperto. --severity CONDITION=LEVEL, ripetibile, imposta il livello di una condizione per questa notifica, ad esempio --severity not_playing=error; conta per --min-severity. Teams e PagerDuty mostrano sempre il livello, il testo di e-mail, Slack e Telegram lo indica quando la notifica imposta --min-severity o --severity, e il corpo di un webhook porta severity.

--active-hours SPEC invia gli avvisi aperti solo all'interno di finestre settimanali, lette in --timezone ZONE, che è obbligatorio. SPEC è DAYS HH:MM-HH:MM, ad esempio "Mon-Fri 08:00-22:00"; ripetilo fino a 16 volte. Con --outside-hours hold, il valore predefinito, un avviso in scadenza fuori orario attende la finestra successiva e parte allora se la sua condizione persiste, quindi una condizione che rientra prima non invia nulla. Con drop l'avviso viene saltato come outside_hours, che notifications deliveries elenca. Un avviso di risoluzione per un avviso aperto che è stato inviato parte sempre, crashing segue gli orari come qualsiasi altra condizione, un posticipo viene controllato per primo, e notifications test ignora orari, gravità e pubblico.

--audience FILE (JSON inline, un file o - per stdin) sceglie gli schermi con le regole di un pubblico di campagna, ad esempio {"all":[{"tag":"level2"},{"tag":"overhead"}]} per gli schermi con entrambi i tag; --all-tags TAG e --any-tag TAG sono le scorciatoie per una regola all e una any di tag, e --tag indica uno qualsiasi dei tag. --tag, --any-tag, --all-tags e --audience si escludono a vicenda.

loop_stalled, glass_blank e glass_frozen sono verdetti che screenRIG trae dai report di riproduzione e dagli screenshot che riceve, e lasciano fuori ciò che non possono giudicare: uno schermo offline, con il display spento, sotto takeover o sospeso, che mostra una sola immagine fissa o un video wall, o il cui Player non invia numeri di riproduzione. Quando screenRIG smette di giudicare uno schermo che aveva trovato in uno di questi stati, l’alert si chiude, ma e-mail, Slack, Teams e Telegram non inviano alcun avviso di risoluzione, perché nulla ha mostrato lo schermo ripristinarsi; PagerDuty risolve comunque il suo incidente.

source_failed e source_stale controllano le fonti di dati del progetto, non i suoi schermi: un avviso nomina la fonte e collega la sua pagina, e --tag non corrisponde mai a una fonte.

card_data_stale osserva una scheda, non uno schermo. Scrivi i dati di una scheda con una scadenza commisurata alla pianificazione di chi li scrive (card data put --ttl 30m): quando il job o l’agente che li rinnova si ferma, i dati scadono, la scheda è vuota su ogni schermo che la mostra, e questa condizione te lo segnala. L’avviso nomina la scheda e quando i suoi dati sono scaduti, e collega l’editor di pagine su una pagina che la colloca. I documenti di un’origine dati non vengono mai annunciati qui (source_stale li copre), né una scheda che nessuno schermo mostra, dati scritti senza scadenza o dati eliminati. --tag non corrisponde mai a una scheda.

reach_dropped e group_empty controllano una campagna, non uno schermo. L'avviso nomina la campagna e gli schermi che raggiungeva prima e che raggiunge ora, oppure il tag o la cartella vuoti, e rimanda al calendario della campagna. Una campagna appartiene al progetto, quindi --tag, --any-tag, --all-tags e --audience non le limitano mai; --min-severity, --severity, --active-hours e --hold valgono come per qualsiasi condizione, ed entrambe sono warning per impostazione predefinita. --reach-drop-screens N e --reach-drop-percent P inviano un avviso reach_dropped solo per un calo di almeno N schermi e di almeno P percento degli schermi che la campagna raggiungeva quando è stata pubblicata; un calo deve soddisfare entrambi, e senza di essi qualsiasi calo notifica. Richiedono reach_dropped in --conditions. Ogni tag o cartella vuoti di una campagna sono un avviso a sé, e notifications deliveries lo mostra come audience_group (tag:Lobby o folder:sfd_…). Una pubblicazione che rimuove un gruppo vuoto dal pubblico chiude un incidente PagerDuty e un alert del webhook, ma non invia alcuna email o messaggio di chat di ripristino.

L’email arriva all’indirizzo verificato di ogni destinatario, un’email per destinatario per tutto ciò che va inviato entro circa due minuti, con un link a ogni schermo e alla notifica nella dashboard. I destinatari sono owner, chiunque possieda il progetto quando l’avviso viene inviato, e gli ID utente dei membri del progetto. Un destinatario senza indirizzo verificato, o che ha lasciato il progetto, viene saltato. Le email di notifica e gli avvisi di schermo sono gratuiti.

Ogni email contiene un link di annullamento dell’iscrizione per il suo destinatario: il pulsante di annullamento iscrizione delle app di posta e un link nel piè di pagina. Seguirlo interrompe le email di quella notifica per quella sola persona, senza accedere, e la pagina che si apre ha un pulsante Resubscribe. Gli altri destinatari non sono interessati e la persona resta tra i destinatari. notifications show elenca chi ha annullato l’iscrizione con unsubscribed, e notifications resubscribe le invia di nuovo le email. Un avviso senza nessuno a cui scrivere viene saltato come no_recipients.

Una notifica webhook invia ogni avviso come JSON via POST; lo verifichi come descritto in Verifica una consegna. Con --events invia anche gli eventi grezzi del progetto, via POST, man mano che accadono; quelle consegne sono conteggiate come descritto in Webhook.

Una notifica Slack, Teams, PagerDuty o Telegram pubblica un messaggio per interruzione e per schermo, o per gruppo di schermi: lo schermo, cosa è cambiato, da quando, il progetto, un link allo schermo e, quando uno schermo offline torna, la causa probabile se è già nota. Un messaggio di ripristino segue una volta inviato il primo e, in PagerDuty, risolve l'incidente aperto dal primo. La credenziale si indica una sola volta (--slack accetta l'URL di un webhook in entrata, --teams l'URL di un webhook di Workflows, --pagerduty una chiave di instradamento dell'API Events v2, --telegram un token di bot con --telegram-chat); viene sigillata, non viene mai più mostrata e destination_hint ne mostra solo la fine mascherata. Un - la legge da una riga di stdin così non finisce nella cronologia della tua shell. Una pubblicazione fallita viene ritentata per 24 ore, e una notifica che fallisce per 72 ore viene disattivata.

Quando tre o più schermi entrano nella stessa condizione a meno di cinque minuti l’uno dall’altro e condividono rete, posizione, modello, versione del Player o tag, una notifica e-mail, Slack, Teams, PagerDuty o Telegram invia un solo avviso per loro invece di uno per schermo, e un solo avviso dice il gruppo quando si ripristina il suo ultimo schermo; l’avviso di ogni altro schermo viene saltato come grouped. Un webhook invia comunque un avviso per schermo.

Leggere le notifiche e le loro consegne richiede l’accesso Solo lettura; creare, modificare, testare ed eliminare una notifica, ruotarne il segreto e reiscrivere una persona richiedono l’accesso Gestire.

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

Verifica una consegna

Il corpo di un avviso di schermo è JSON: type (alert.opened o alert.resolved), id (l’ID della consegna), notification_id, project_id, condition, screen (id e name), since (quando la condizione è iniziata), at (quando è durata abbastanza a lungo, o si è risolta), event_id e severity (info, warning o error: il livello della condizione su alert.opened, info su alert.resolved). alert.resolved per screen_offline porta anche likely_cause (device_restart, app_crash, app_restart, network o platform), null finché la causa è sconosciuta. Per un’origine dati, una campagna o una scheda, screen la nomina, e un avviso di campagna aggiunge reach (published e current schermi) per reach_dropped o audience_group (kind tag o folder e value) per group_empty. Un evento grezzo da --events è lo stesso oggetto JSON che events list restituisce. Gli header sono ScreenRig-Webhook-Id (l’ID della notifica), ScreenRig-Event-Id (stabile tra i retry: l’ID della consegna per un avviso, il cursore dell’evento per un evento) e ScreenRig-Signature: t=<unix seconds>,v1=<hex>, dove v1 è HMAC-SHA256 su "<t>.<raw body>" con chiave la stringa segreta. Calcolalo sui byte grezzi prima di analizzare JSON, confronta in tempo costante, rifiuta un vecchio t e deduplica su ScreenRig-Event-Id, perché la consegna avviene almeno una volta e non in ordine. Rispondi 2xx entro 10 secondi; i redirect non vengono seguiti.

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);
}

Alert

Un alert è un problema su uno schermo finché dura. Si apre quando uno schermo entra in una delle condizioni di notifica dello schermo (screen_offline, display_disconnected, running_hot, on_battery, storage_full, content_stuck, not_playing, loop_stalled, glass_blank o glass_frozen), che una notifica la controlli o no, e si risolve quando la condizione termina. Uno schermo ha al massimo un alert aperto per condizione. Un picco di crash, un’origine dati, una scheda e una campagna sono avvisi, mai alert. Uno schermo che si riavvia per un riavvio inviato da screenRIG (screen reboot o una pianificazione di riavvio) non apre alert screen_offline o display_disconnected finché il riavvio non è completato o fino a dieci minuti dopo il suo invio; una condizione che persiste ancora allora apre il suo alert. alerts list mostra ciò che è aperto adesso.

Un alert aperto richiede attenzione finché qualcuno non lo riconosce o lo posticipa, o finché un silenziamento non copre il suo schermo. Riconoscere significa che qualcuno se ne sta occupando: l’alert resta aperto, registra chi lo ha riconosciuto e quando, e non richiede attenzione fino alla risoluzione. Posticipare riconosce fino a un momento al massimo 30 giorni più avanti, e l’alert richiede di nuovo attenzione allora se è ancora aperto. Un riconoscimento o un posticipo successivo sostituisce il precedente. Finché un alert è riconosciuto o posticipato, l’avviso di una notifica che lo riguarda e che è ancora nel tempo di attesa viene saltato.

Un silenziamento serve per la manutenzione: indica schermi, tag o entrambi e termina in un momento al massimo 30 giorni più avanti. Copre uno schermo finché il suo ID è nell’elenco o ha un tag dell’elenco, quindi uno schermo taggato in seguito è coperto e uno che perde il tag non lo è più. Gli alert di uno schermo silenziato si aprono e si risolvono comunque, contrassegnati muted, ma non richiedono mai attenzione, e ogni notifica salta i loro avvisi. Un’organizzazione ha al massimo 50 silenziamenti attivi in tutti i suoi progetti.

counts.attention in alerts list è il numero che la dashboard mostra accanto ad Alert. Aprire, risolvere e riconoscere un alert aggiunge screen.alert_opened, screen.alert_resolved e screen.alert_acknowledged al registro eventi del progetto, e creare e terminare un silenziamento aggiunge alert_mute.created e alert_mute.deleted. Sono gratuiti sul flusso di ascolto e sui webhook, come ogni evento screen.*. Gli alert risolti restano elencati per la durata di conservazione eventi del piano. Leggere alert e silenziamenti richiede l’accesso Solo lettura; riconoscere, posticipare, silenziare e rimuovere un silenziamento richiedono l’accesso Gestire.

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

Webhook

Un webhook invia gli eventi di questo progetto a un endpoint HTTPS che gestisci come POST firmati, così un evento corrispondente può svegliare un agente, un bot o il tuo servizio. Ogni evento corrispondente arriva come lo stesso oggetto JSON che events list restituisce. Un webhook è una notifica nella sua forma originale: rientra nelle 50 notifiche dell’organizzazione e notifications list lo mostra. Per il nuovo lavoro usa notifications, che invia anche email e avvisi di schermo.

Ogni tentativo di consegna è gratuito e non conta nel limite orario di richieste agente dell’organizzazione.

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 risponde con webhook_limit_reached (uscita 5) quando l’organizzazione ha già 50 notifiche, mentre notifications create risponde con notification_limit_reached. Un URL rifiutato è webhook_url_rejected (uscita 8) in entrambi i casi.

--url accetta un URL https sulla porta 443 o 8443 il cui host risolve solo indirizzi pubblici Internet, verificato come per notifications create; un URL che contiene credenziali o un frammento # viene rifiutato localmente con uscita 2. --event-types accetta da 1 a 32 tipi esatti separati da virgole, come screen.online, o prefissi che terminano con .*, come screen.*. --description è lungo al massimo 200 caratteri. --disabled crea il webhook disabilitato. webhooks update --enable cancella lo stato di errore e riparte dall’evento corrente, quindi non viene inviato nulla di ciò che è successo mentre era disabilitato, e --disable fa fallire le consegne in sospeso con webhook_disabled. --expect-rev protegge la revisione (revision_conflict, uscita 6).

webhooks create e webhooks rotate-secret stampano il segreto di firma una sola volta in data.secret con l’avviso webhook_secret_shown_once; dopo una chiamata interrotta o ambigua, riesegui lo stesso comando entro 24 ore per ottenere di nuovo la stessa risposta. La consegna inizia con il primo evento successivo alla creazione del webhook. webhooks test mette in coda una consegna webhook.test solo per questo webhook; funziona su un webhook disabilitato, viene tentata una volta senza ritentativi, è misurata come qualsiasi consegna ed è limitata a 20 al minuto per organizzazione (rate_limited, uscita 7). webhooks list mostra le notifiche webhook di questo progetto, dalla più vecchia alla più recente, e una credenziale di sola lettura riceve ogni url vuoto con url_redacted true. webhooks deliveries legge il registro partendo dall’evento più recente, da 1 a 200 righe per pagina (predefinito 50), con next_cursor (whc1_…) come --before; il state di una riga è pending, succeeded o failed, con last_status e una classe last_error fissa. Verifica una consegna come descritto in Verifica una consegna.