Notificaciones: comandos CLI

Operaciones

Las cargas y las publicaciones se ejecutan como operaciones. media upload, media replace y app upload esperan la suya de forma predeterminada; estos comandos sirven para terminar una que dejó en ejecución 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

Eventos

El registro de eventos del proyecto registra lo que hizo el proyecto y lo que hizo la flota. Una versión publicada añade application.published; una app que llama a screenrig.emit(code) añade su propio evento, que es la evidencia más directa de que se ejecutó en una pantalla.

La presencia también está en el registro. screen.offline se escribe una vez que una pantalla ha estado sin conexión por 60 segundos, y screen.online cuando vuelve; una reconexión dentro de esos 60 segundos no escribe ninguno. screen.offline lleva details.offline_since y, cuando la pantalla ha estado en línea antes, details.last_online_at. screen.online lleva details.last_online_at, más details.offline_at cuando la pantalla estuvo sin conexión antes de volver. Como cada evento screen.*, son gratuitos en el flujo de escucha, por lo que un agente puede mantener events follow abierto para observar una flota.

Las actualizaciones de contenido de un Player llegan como screen.manifest_changed, screen.manifest_activated y screen.manifest_upgrade, cuyos details incluyen manifest_revision, state y, cuando existen, code y attempt. Una actualización failed tiene gravedad de error, y retrying, blocked y partial son advertencias.

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

Notificaciones

Una notificación avisa a una persona, o a otro sistema, cuando una pantalla cambia de estado. Una notificación por correo envía un correo a cada destinatario, una notificación webhook envía un POST HTTPS firmado y una notificación de Slack, Teams, PagerDuty o Telegram publica un mensaje en un chat o en un sistema de guardia. Una organización tiene como máximo 50 entre todos los canales y todos sus proyectos, y cada proyecto empieza con un correo a su propietario cuando una pantalla lleva 10 minutos sin conexión.

Una notificación vigila las condiciones que usted nombra:

Una condición notifica una vez que ha durado --hold minutos (10 por defecto), para que una reconexión rápida no genere avisos. Si termina antes, no se envía nada; si termina después de que se haya enviado un aviso, sigue un aviso de resolución. crashing se envía de inmediato. Un aviso también se omite cuando alguien reconoce o pospone la alerta de la pantalla durante el tiempo de espera, o cuando un silenciamiento cubre la pantalla. --tag limita una notificación a las pantallas que llevan esa etiqueta; sin ella, se consideran todas las pantallas.

Cada aviso tiene una gravedad. Un aviso abierto es error para screen_offline y warning para cualquier otra condición, y un aviso resuelto o una prueba es info. --min-severity LEVEL (info, warning o error) no crea ningún aviso abierto por debajo de ese nivel, y un aviso resuelto sigue a su aviso abierto. --severity CONDITION=LEVEL, repetible, define el nivel de una condición para esta notificación, como --severity not_playing=error; cuenta para --min-severity. Teams y PagerDuty siempre muestran el nivel, el texto de correo, Slack y Telegram lo nombra cuando la notificación define --min-severity o --severity, y el cuerpo de un webhook incluye severity.

--active-hours SPEC envía los avisos abiertos solo dentro de ventanas semanales, leídas en --timezone ZONE, que lo requiere. SPEC es DAYS HH:MM-HH:MM, como "Mon-Fri 08:00-22:00"; repítalo hasta 16 veces. Con --outside-hours hold, el valor predeterminado, un aviso que vence fuera del horario espera a la siguiente ventana y se envía entonces si su condición sigue vigente, de modo que una condición que se despeja antes no envía nada. Con drop el aviso se omite como outside_hours, que notifications deliveries lista. Un aviso resuelto de un aviso abierto que se envió siempre se envía, crashing sigue el horario como cualquier otra condición, primero se comprueba un aplazamiento, y notifications test ignora el horario, la gravedad y la audiencia.

--audience FILE (JSON en línea, un archivo o - para stdin) elige las pantallas con las reglas de una audiencia de campaña, como {"all":[{"tag":"level2"},{"tag":"overhead"}]} para las pantallas que llevan ambas etiquetas; --all-tags TAG y --any-tag TAG son las abreviaturas de una regla all y una regla any de etiquetas, y --tag significa cualquiera de las etiquetas. --tag, --any-tag, --all-tags y --audience se excluyen entre sí.

loop_stalled, glass_blank y glass_frozen son veredictos que screenRIG saca de los informes de reproducción y las capturas de pantalla que recibe, y dejan fuera lo que no pueden juzgar: una pantalla sin conexión, con la pantalla apagada, bajo una toma de control o suspendida, que muestra una sola imagen fija o un muro de vídeo, o cuyo Player no envía números de reproducción. Cuando screenRIG deja de juzgar una pantalla que había encontrado en uno de ellos, la alerta se cierra, pero el correo, Slack, Teams y Telegram no envían aviso de resolución, porque nada mostró que la pantalla se recuperara; PagerDuty sí resuelve su incidente.

source_failed y source_stale vigilan las fuentes de datos del proyecto, no sus pantallas: un aviso nombra la fuente y enlaza su página, y --tag nunca coincide con una fuente.

card_data_stale vigila una tarjeta, no una pantalla. Escriba los datos de una tarjeta con una caducidad ajustada al calendario de quien los escribe (card data put --ttl 30m), y cuando el trabajo o el agente que los renueva se detiene, los datos caducan, la tarjeta queda en blanco en cada pantalla que la muestra, y esta condición se lo avisa. El aviso nombra la tarjeta y cuándo caducaron sus datos, y enlaza el editor de páginas en una página que la coloca. Los documentos de una fuente de datos nunca se anuncian aquí (source_stale los cubre), ni tampoco una tarjeta que ninguna pantalla muestra, datos escritos sin caducidad o datos eliminados. --tag nunca coincide con una tarjeta.

reach_dropped y group_empty vigilan una campaña, no una pantalla. El aviso nombra la campaña y las pantallas que alcanzaba antes y que alcanza ahora, o la etiqueta o carpeta vacía, y enlaza al calendario de la campaña. Una campaña pertenece al proyecto, por lo que --tag, --any-tag, --all-tags y --audience nunca limitan a estos dos; --min-severity, --severity, --active-hours y --hold se aplican como en cualquier condición, y ambos están warning de forma predeterminada. --reach-drop-screens N y --reach-drop-percent P envían un aviso reach_dropped solo por una caída de al menos N pantallas y de al menos P por ciento de las pantallas que la campaña alcanzaba cuando se publicó; una caída debe cumplir ambos, y sin ellos cualquier caída genera un aviso. Requieren reach_dropped en --conditions. Cada etiqueta o carpeta vacía de una campaña es su propio aviso, y notifications deliveries lo muestra como audience_group (tag:Lobby o folder:sfd_…). Una publicación que quita un grupo vacío de la audiencia cierra un incidente de PagerDuty y la alerta de un webhook, pero no envía correo electrónico ni mensaje de chat de recuperación.

El correo electrónico se envía a la dirección verificada de cada destinatario, un correo por destinatario para todo lo que vence en unos dos minutos, con un enlace a cada pantalla y a la notificación en el panel. Los destinatarios son owner, quien sea propietario del proyecto cuando se envía el aviso, y los ids de usuario de los miembros del proyecto. Se omite a un destinatario sin dirección verificada o que ha salido del proyecto. Los correos electrónicos de notificación y los avisos de pantalla son gratuitos.

Cada correo incluye un enlace para cancelar la suscripción de su propio destinatario: el botón de cancelar suscripción de las aplicaciones de correo y un enlace en el pie. Al seguirlo, los correos de esa notificación dejan de llegar a esa única persona, sin iniciar sesión, y la página que se abre tiene un botón Resubscribe. Los demás destinatarios no se ven afectados, y la persona sigue entre los destinatarios. notifications show muestra quién canceló la suscripción con unsubscribed, y notifications resubscribe vuelve a enviarle correos. Un aviso sin nadie a quien enviar correo se omite como no_recipients.

Una notificación de webhook envía por POST cada aviso como JSON, que usted verifica como se describe en Verificar una entrega. Con --events también envía por POST eventos del proyecto sin procesar a medida que ocurren; esas entregas se miden como se describe en Webhooks.

Una notificación de Slack, Teams, PagerDuty o Telegram publica un mensaje por caída y por pantalla, o por grupo de pantallas: la pantalla, qué cambió, desde cuándo, el proyecto, un enlace a la pantalla y, cuando vuelve una pantalla sin conexión, su causa probable si ya se conoce. Un mensaje de recuperación llega cuando se envió el primero y, en PagerDuty, resuelve el incidente que abrió el primero. La credencial se da una sola vez (--slack toma la URL de un webhook entrante, --teams la URL de un webhook de Workflows, --pagerduty una clave de enrutamiento de la API Events v2, --telegram un token de bot con --telegram-chat); queda sellada, no se vuelve a mostrar y destination_hint solo muestra su final enmascarado. Un - la lee desde una línea de stdin para que no quede en el historial de tu shell. Una publicación fallida se reintenta durante 24 horas, y una notificación que falla durante 72 horas se desactiva.

Cuando tres o más pantallas entran en la misma condición con menos de cinco minutos de diferencia y comparten red, ubicación, modelo, versión del Player o etiqueta, una notificación por correo, Slack, Teams, PagerDuty o Telegram envía un solo aviso para ellas en lugar de uno por pantalla, y un solo aviso comunica el grupo cuando se recupera su última pantalla; el aviso de cada otra pantalla se omite como grouped. Un webhook sigue enviando un aviso por pantalla.

Leer las notificaciones y sus entregas requiere el acceso Solo lectura; crear, cambiar, probar y eliminar una, rotar su secreto y volver a suscribir a una persona requieren el acceso Administrar.

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

Verificar una entrega

El cuerpo de un aviso de pantalla es JSON: type (alert.opened o alert.resolved), id (el id de entrega), notification_id, project_id, condition, screen (id y name), since (cuando comenzó la condición), at (cuando duró lo suficiente, o se resolvió), event_id y severity (info, warning o error: el nivel de la condición en alert.opened, info en alert.resolved). alert.resolved para screen_offline también lleva likely_cause (device_restart, app_crash, app_restart, network o platform), null mientras la causa es desconocida. Para una fuente de datos, una campaña o una tarjeta, screen la nombra, y un aviso de campaña añade reach (published y current pantallas) para reach_dropped o audience_group (kind tag o folder, y value) para group_empty. Un evento sin procesar de --events es el mismo objeto JSON que events list devuelve. Los encabezados son ScreenRig-Webhook-Id (el id de la notificación), ScreenRig-Event-Id (estable entre reintentos: el id de entrega para un aviso, el cursor del evento para un evento) y ScreenRig-Signature: t=<unix seconds>,v1=<hex>, donde v1 es HMAC-SHA256 sobre "<t>.<raw body>" con la cadena secreta como clave. Calcúlelo sobre los bytes sin procesar antes de analizar JSON, compárelo en tiempo constante, rechace un t antiguo y deduplique en ScreenRig-Event-Id, porque la entrega es al menos una vez y sin orden. Responda 2xx en 10 segundos; no se siguen las redirecciones.

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

Alertas

Una alerta es un problema en una pantalla mientras dura. Se abre cuando una pantalla entra en una de las condiciones de notificación de pantalla (screen_offline, display_disconnected, running_hot, on_battery, storage_full, content_stuck, not_playing, loop_stalled, glass_blank o glass_frozen), la vigile o no una notificación, y se resuelve cuando la condición termina. Una pantalla tiene como máximo una alerta abierta por condición. Un pico de fallos, una fuente de datos, una tarjeta y una campaña son avisos, nunca alertas. Una pantalla que se reinicia por un reinicio enviado por screenRIG (screen reboot o una programación de reinicios) no abre ninguna alerta screen_offline ni display_disconnected hasta que el reinicio termina o pasan diez minutos desde su envío; una condición que sigue vigente abre entonces su alerta. alerts list muestra lo que está abierto ahora.

Una alerta abierta necesita atención hasta que alguien la reconoce o la pospone, o hasta que un silenciamiento cubre su pantalla. Reconocer significa que alguien se está ocupando: la alerta sigue abierta, registra quién la reconoció y cuándo, y no necesita atención hasta que se resuelve. Posponer reconoce hasta una hora como máximo 30 días en el futuro, y la alerta vuelve a necesitar atención entonces si sigue abierta. Un reconocimiento o aplazamiento posterior reemplaza al anterior. Mientras una alerta está reconocida o pospuesta, se omite el aviso de una notificación sobre ella que aún está en su tiempo de espera.

Un silenciamiento sirve para el mantenimiento: nombra pantallas, etiquetas o ambas, y termina en un momento como máximo 30 días en el futuro. Cubre una pantalla mientras su id figure en la lista o lleve una etiqueta de la lista, de modo que una pantalla etiquetada después queda cubierta y una que pierde la etiqueta deja de estarlo. Las alertas de una pantalla silenciada siguen abriéndose y resolviéndose, marcadas muted, pero nunca necesitan atención, y todas las notificaciones omiten sus avisos. Una organización tiene como máximo 50 silenciamientos vigentes en todos sus proyectos.

counts.attention en alerts list es el número que el panel muestra junto a Alertas. Abrir, resolver y reconocer una alerta agrega screen.alert_opened, screen.alert_resolved y screen.alert_acknowledged al registro de eventos del proyecto, y crear y finalizar un silenciamiento agrega alert_mute.created y alert_mute.deleted. Son gratuitos en el flujo de escucha y en los webhooks, como todo evento screen.*. Las alertas resueltas siguen en la lista durante la retención de eventos del plan. Leer alertas y silenciamientos requiere el acceso Solo lectura; reconocer, posponer, silenciar y quitar el silencio requieren el acceso Administrar.

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 envía los eventos propios de este proyecto a un endpoint HTTPS que usted ejecuta como POST firmados, para que un evento coincidente pueda despertar a un agente, a un bot o a su propio servicio. Cada evento coincidente llega como el mismo objeto JSON que events list devuelve. Un webhook es una notificación en su forma original: cuenta para las 50 notificaciones de la organización, y notifications list lo muestra. El trabajo nuevo usa notifications, que también envía correo electrónico y avisos de pantalla.

Cada intento de entrega es gratuito y no cuenta para el límite por hora de solicitudes de agentes de la organización.

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 responde webhook_limit_reached (salida 5) cuando la organización ya tiene 50 notificaciones, mientras que notifications create responde notification_limit_reached. Una URL rechazada es webhook_url_rejected (salida 8) en ambos casos.

--url toma una URL https en el puerto 443 o 8443 cuyo host resuelve solo a direcciones públicas de Internet, comprobada como en notifications create; una URL que lleva credenciales o un fragmento # se rechaza localmente con salida 2. --event-types toma de 1 a 32 tipos exactos separados por comas, como screen.online, o prefijos que terminan en .*, como screen.*. --description tiene como máximo 200 caracteres. --disabled crea el webhook deshabilitado. webhooks update --enable borra el estado de fallo y empieza en el evento actual, de modo que no se envía nada de lo ocurrido mientras estuvo deshabilitado, y --disable hace fallar las entregas pendientes con webhook_disabled. --expect-rev protege la revisión (revision_conflict, salida 6).

webhooks create y webhooks rotate-secret imprimen una sola vez el secreto de firma en data.secret con la advertencia webhook_secret_shown_once; tras una llamada interrumpida o ambigua, vuelva a ejecutar el mismo comando dentro de las 24 horas para recibir de nuevo la misma respuesta. La entrega empieza con el primer evento posterior a la creación del webhook. webhooks test pone en cola una entrega webhook.test solo para este webhook; funciona con un webhook deshabilitado, se intenta una vez sin reintentos, se mide como cualquier entrega y está limitada a 20 por minuto por organización (rate_limited, salida 7). webhooks list muestra las notificaciones webhook de este proyecto, de la más antigua a la más reciente, y una credencial de solo lectura recibe cada url vacío con url_redacted en true. webhooks deliveries lee el registro empezando por el evento más reciente, de 1 a 200 filas por página (50 por defecto), con next_cursor (whc1_…) como --before; el state de una fila es pending, succeeded o failed, con last_status y una clase last_error fija. Verifique una entrega como se describe en Verificar una entrega.