Notificações: comandos da CLI

Operações

Uploads e publicações são executados como operações. media upload, media replace e app upload aguardam a sua por padrão; estes comandos servem para concluir uma que você deixou em execução com --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

O registro de eventos do projeto registra o que o projeto fez e o que a frota fez. Um lançamento publicado adiciona application.published; um app que chama screenrig.emit(code) adiciona seu próprio evento, que é a evidência mais direta de que ele foi executado em uma tela.

Presença também está no log. screen.offline é gravado uma vez que uma tela fica offline por 60 segundos, e screen.online quando ela volta; uma reconexão dentro desses 60 segundos não grava nenhum dos dois. screen.offline carrega details.offline_since e, quando a tela já esteve online antes, details.last_online_at. screen.online carrega details.last_online_at, mais details.offline_at quando a tela estava offline antes de retornar. Como todo evento screen.*, eles são gratuitos na corrente de escuta, para que um agente possa manter events follow aberto para monitorar uma frota.

As atualizações de conteúdo de um Player chegam como screen.manifest_changed, screen.manifest_activated e screen.manifest_upgrade, cujos details trazem manifest_revision, state e, quando presentes, code e attempt. Um upgrade failed tem gravidade de erro, e retrying, blocked e partial são avisos.

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

Notificações

Uma notificação avisa uma pessoa, ou outro sistema, quando uma tela muda de estado. Uma notificação por e-mail envia um e-mail a cada destinatário, uma notificação de webhook envia um POST HTTPS assinado, e uma notificação do Slack, Teams, PagerDuty ou Telegram publica uma mensagem em um chat ou em um sistema de plantão. Uma organização tem no máximo 50, somando todos os canais e todos os seus projetos, e todo projeto começa com um e-mail ao proprietário quando uma tela fica 10 minutos offline.

Uma notificação observa as condições que você indicar:

Uma condição notifica depois de durar --hold minutos (padrão 10), para que uma reconexão rápida fique silenciosa. Se ela terminar antes, nada é enviado; se terminar depois de um aviso ter sido enviado, um aviso de resolução vem em seguida. crashing é enviado imediatamente. Um aviso também é ignorado quando alguém reconhece ou adia o alerta da tela durante o tempo de espera, ou quando um silenciamento cobre a tela. --tag limita uma notificação às telas com essa tag; sem ela, todas as telas são consideradas.

Cada aviso tem uma severidade. Um aviso aberto é error para screen_offline e warning para toda outra condição, e um aviso de resolvido ou um teste é info. --min-severity LEVEL (info, warning ou error) não cria aviso aberto abaixo desse nível, e um aviso de resolvido segue o seu aberto. --severity CONDITION=LEVEL, repetível, define o nível de uma condição para esta notificação, como --severity not_playing=error; conta para --min-severity. Teams e PagerDuty sempre mostram o nível, o texto de e-mail, Slack e Telegram o nomeia quando a notificação define --min-severity ou --severity, e o corpo de um webhook carrega severity.

--active-hours SPEC envia avisos abertos somente dentro de janelas semanais, lidas em --timezone ZONE, que ele exige. SPEC é DAYS HH:MM-HH:MM, como "Mon-Fri 08:00-22:00"; repita até 16 vezes. Com --outside-hours hold, o padrão, um aviso que vence fora do horário espera a próxima janela e é enviado então se sua condição ainda se mantiver, de modo que uma condição que termina antes não envia nada. Com drop o aviso é ignorado como outside_hours, que notifications deliveries lista. Um aviso de resolvido para um aviso aberto que foi enviado sempre é enviado, crashing segue o horário como qualquer outra condição, um adiamento é verificado primeiro, e notifications test ignora horário, severidade e público-alvo.

--audience FILE (JSON inline, um arquivo ou - para stdin) escolhe as telas com as regras de um público-alvo de campanha, como {"all":[{"tag":"level2"},{"tag":"overhead"}]} para telas com ambas as tags; --all-tags TAG e --any-tag TAG são os atalhos para uma regra all e uma regra any de tags, e --tag significa qualquer uma das tags. --tag, --any-tag, --all-tags e --audience são mutuamente excludentes.

loop_stalled, glass_blank e glass_frozen são veredictos que o screenRIG tira dos relatórios de reprodução e das capturas de tela que recebe, e deixam de fora o que não conseguem julgar: uma tela offline, com o display desligado, sob takeover ou suspensa, que mostra uma única imagem estática ou um video wall, ou cujo Player não envia números de reprodução. Quando o screenRIG deixa de julgar uma tela que havia encontrado em um deles, o alerta se fecha, mas e-mail, Slack, Teams e Telegram não enviam aviso de resolução, pois nada mostrou a tela se recuperando; o PagerDuty ainda resolve o incidente.

source_failed e source_stale acompanham as fontes de dados do projeto, não as telas: um aviso nomeia a fonte e liga à página dela, e --tag nunca corresponde a uma fonte.

card_data_stale vigia um cartão, não uma tela. Grave os dados de um cartão com uma expiração dimensionada pelo horário de quem os grava (card data put --ttl 30m), e quando o job ou agente que os renova para, os dados expiram, o cartão fica em branco em toda tela que o mostra, e esta condição avisa você. O aviso nomeia o cartão e quando os dados dele expiraram, e liga ao editor de páginas em uma página que o coloca. Os documentos de uma fonte de dados nunca são anunciados aqui (source_stale os cobre), nem um cartão que nenhuma tela mostra, dados gravados sem expiração ou dados excluídos. --tag nunca corresponde a um cartão.

reach_dropped e group_empty observam uma campanha, não uma tela. O aviso nomeia a campanha e as telas que ela alcançava antes e alcança agora, ou a tag ou pasta vazia, e traz um link para o calendário da campanha. Uma campanha pertence ao projeto, portanto --tag, --any-tag, --all-tags e --audience nunca limitam esses dois; --min-severity, --severity, --active-hours e --hold se aplicam como em qualquer condição, e ambos são warning por padrão. --reach-drop-screens N e --reach-drop-percent P enviam um aviso reach_dropped somente para uma queda de pelo menos N telas e de pelo menos P por cento das telas que a campanha alcançava quando foi publicada; uma queda precisa atender aos dois critérios, e sem eles qualquer queda gera aviso. Eles exigem reach_dropped em --conditions. Cada tag ou pasta vazia de uma campanha é um aviso próprio, e notifications deliveries o mostra como audience_group (tag:Lobby ou folder:sfd_…). Uma publicação que remove um grupo vazio do público-alvo encerra um incidente do PagerDuty e o alerta de um webhook, mas não envia e-mail nem mensagem de chat de recuperação.

O e-mail vai para o endereço verificado de cada destinatário, um e-mail por destinatário para tudo o que deve ser enviado dentro de cerca de dois minutos, com um link para cada tela e para a notificação no dashboard. Os destinatários são owner, quem for o proprietário do projeto quando o aviso é enviado, e os ids de usuário dos membros do projeto. Um destinatário sem endereço verificado, ou que saiu do projeto, é ignorado. Os e-mails de notificação e os avisos de tela são gratuitos.

Cada e-mail traz um link de cancelamento de inscrição para o próprio destinatário: o botão de cancelar inscrição dos apps de e-mail e um link no rodapé. Segui-lo interrompe os e-mails dessa notificação para essa única pessoa, sem fazer login, e a página aberta tem um botão Resubscribe. Os outros destinatários não são afetados, e a pessoa continua entre os destinatários. notifications show lista quem cancelou com unsubscribed, e notifications resubscribe volta a enviar e-mails para ela. Um aviso sem ninguém para receber o e-mail é ignorado como no_recipients.

Uma notificação por webhook envia cada aviso por POST, como JSON, e você o verifica conforme descrito em Verificar uma entrega. Com --events, ela também envia por POST eventos brutos do projeto à medida que acontecem; essas entregas são medidas conforme descrito em Webhooks.

Uma notificação do Slack, Teams, PagerDuty ou Telegram publica uma mensagem por queda e por tela, ou por grupo de telas: a tela, o que mudou, desde quando, o projeto, um link para a tela e, quando uma tela offline volta, a causa provável se já for conhecida. Uma mensagem de recuperação vem depois que a primeira foi enviada e, no PagerDuty, resolve o incidente que a primeira abriu. Você informa a credencial uma única vez (--slack recebe a URL de um webhook de entrada, --teams a URL de um webhook do Workflows, --pagerduty uma chave de roteamento da API Events v2, --telegram um token de bot com --telegram-chat); ela é selada, nunca é mostrada de novo, e destination_hint mostra só o final mascarado. Um - a lê de uma linha do stdin para que fique fora do histórico do seu shell. Uma publicação com falha é repetida por 24 horas, e uma notificação que falha por 72 horas é desativada.

Quando três ou mais telas entram na mesma condição com menos de cinco minutos de diferença e compartilham rede, localização, modelo, versão do Player ou tag, uma notificação por e-mail, Slack, Teams, PagerDuty ou Telegram envia um único aviso para elas em vez de um por tela, e um único aviso diz o grupo quando a última tela se recupera; o aviso de cada outra tela é ignorado como grouped. Um webhook continua enviando um aviso por tela.

Ler notificações e suas entregas exige o acesso Somente leitura; criar, alterar, testar e excluir uma, girar o segredo dela e reinscrever uma pessoa exigem o acesso Gerenciar.

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 uma entrega

O corpo de um aviso de tela é JSON: type (alert.opened ou alert.resolved), id (o id da entrega), notification_id, project_id, condition, screen (id e name), since (quando a condição começou), at (quando durou o suficiente, ou terminou), event_id e severity (info, warning ou error: o nível da condição em alert.opened, info em alert.resolved). alert.resolved para screen_offline também traz likely_cause (device_restart, app_crash, app_restart, network ou platform), null enquanto a causa é desconhecida. Para uma fonte de dados, uma campanha ou um cartão, screen o nomeia, e um aviso de campanha acrescenta reach (published e current telas) para reach_dropped ou audience_group (kind tag ou folder e value) para group_empty. Um evento bruto de --events é o mesmo objeto JSON que events list retorna. Os cabeçalhos são ScreenRig-Webhook-Id (o id da notificação), ScreenRig-Event-Id (estável entre as tentativas: o id da entrega para um aviso, o cursor do evento para um evento) e ScreenRig-Signature: t=<unix seconds>,v1=<hex>, onde v1 é HMAC-SHA256 sobre "<t>.<raw body>" usando a string secreta como chave. Calcule-o sobre os bytes brutos antes de analisar o JSON, compare em tempo constante, rejeite um t antigo e deduplique por ScreenRig-Event-Id, porque a entrega é pelo menos uma vez e fora de ordem. Responda 2xx em até 10 segundos; redirecionamentos não são seguidos.

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

Um alerta é um problema em uma tela enquanto ele durar. Ele abre quando uma tela entra em uma das condições de notificação de tela (screen_offline, display_disconnected, running_hot, on_battery, storage_full, content_stuck, not_playing, loop_stalled, glass_blank ou glass_frozen), quer uma notificação a monitore ou não, e é resolvido quando a condição termina. Uma tela tem no máximo um alerta aberto por condição. Um pico de travamentos, uma fonte de dados, um cartão e uma campanha são avisos, nunca alertas. Uma tela que reinicia por uma reinicialização enviada pelo screenRIG (screen reboot ou um agendamento de reinicialização) não abre alerta screen_offline nem display_disconnected até que a reinicialização termine ou dez minutos após o envio; uma condição que ainda persiste então abre o seu alerta. alerts list mostra o que está aberto agora.

Um alerta aberto precisa de atenção até alguém reconhecê-lo ou adiá-lo, ou até um silenciamento cobrir a tela dele. Reconhecer significa que alguém está cuidando: o alerta continua aberto, registra quem o reconheceu e quando, e não precisa de atenção até ser resolvido. Adiar reconhece até um horário no máximo 30 dias à frente, e o alerta volta a precisar de atenção nesse horário se ainda estiver aberto. Um reconhecimento ou adiamento posterior substitui o anterior. Enquanto um alerta está reconhecido ou adiado, o aviso de uma notificação sobre ele que ainda está em tempo de espera é ignorado.

Um silenciamento serve para manutenção: ele nomeia telas, tags ou ambos e termina em um momento no máximo 30 dias à frente. Ele cobre uma tela enquanto o id da tela estiver na lista ou ela tiver uma tag da lista, então uma tela marcada depois fica coberta e uma que perde a tag deixa de ser coberta. Os alertas de uma tela silenciada continuam abrindo e resolvendo, marcados muted, mas nunca precisam de atenção, e toda notificação ignora os avisos deles. Uma organização tem no máximo 50 silenciamentos vigentes em todos os seus projetos.

counts.attention em alerts list é o número que o painel mostra ao lado de Alertas. Abrir, resolver e reconhecer um alerta adiciona screen.alert_opened, screen.alert_resolved e screen.alert_acknowledged ao registro de eventos do projeto, e criar e encerrar um silenciamento adiciona alert_mute.created e alert_mute.deleted. Eles são gratuitos no stream de escuta e nos webhooks, como todo evento screen.*. Os alertas resolvidos continuam listados pelo período de retenção de eventos do plano. Ler alertas e silenciamentos exige o acesso Somente leitura; reconhecer, adiar, silenciar e remover o silenciamento exigem o acesso Gerenciar.

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

Um webhook envia os próprios eventos deste projeto, como POSTs assinados, para um endpoint HTTPS que você executa, para que um evento correspondente possa acordar um agente, um bot ou seu próprio serviço. Cada evento correspondente chega como o mesmo objeto JSON que events list retorna. Um webhook é uma notificação em sua forma original: conta para o limite de 50 notificações da organização, e notifications list o mostra. Os trabalhos novos usam notifications, que também envia e-mail e avisos de tela.

Cada tentativa de entrega é gratuita e não conta no limite por hora de solicitações de agente da organização.

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 (saída 5) quando a organização já tem 50 notificações, enquanto notifications create responde notification_limit_reached. Uma URL recusada é webhook_url_rejected (saída 8) nos dois casos.

--url aceita uma URL https na porta 443 ou 8443 cujo host resolve apenas para endereços públicos da Internet, verificada como em notifications create; uma URL que traga credenciais ou um fragmento # é recusada localmente com saída 2. --event-types aceita de 1 a 32 tipos exatos separados por vírgula, como screen.online, ou prefixos terminados em .*, como screen.*. --description tem no máximo 200 caracteres. --disabled cria o webhook desativado. webhooks update --enable limpa o estado de falha e começa no evento atual, então nada do que aconteceu enquanto ele esteve desativado é enviado, e --disable faz as entregas pendentes falharem com webhook_disabled. --expect-rev protege a revisão (revision_conflict, saída 6).

webhooks create e webhooks rotate-secret imprimem o segredo de assinatura uma só vez em data.secret com o aviso webhook_secret_shown_once; após uma chamada interrompida ou ambígua, execute novamente o mesmo comando em até 24 horas para receber a mesma resposta de volta. A entrega começa com o primeiro evento depois que o webhook é criado. webhooks test enfileira uma entrega webhook.test apenas para este webhook; funciona em um webhook desativado, é tentada uma vez sem novas tentativas, é medida como qualquer entrega e é limitada a 20 por minuto por organização (rate_limited, saída 7). webhooks list mostra as notificações webhook deste projeto, da mais antiga para a mais recente, e uma credencial somente leitura recebe cada url vazio com url_redacted true. webhooks deliveries lê o registro começando pelo evento mais recente, de 1 a 200 linhas por página (padrão 50), com next_cursor (whc1_…) como --before; o state de uma linha é pending, succeeded ou failed, com last_status e uma classe last_error fixa. Verifique uma entrega como descrito em Verificar uma entrega.