Campanhas: comandos da CLI

Listar as campanhas do projeto na ordem em que as telas as leem.

campaign list

Sem parâmetros.

screenrig campaign list

data.items contém no máximo 100 campanhas, maior prioridade primeiro e, dentro de uma prioridade, a mais recente primeiro. Cada uma traz os campos que campaign show retorna, com reach depois de contada. Uma campanha pausada é listada e não se aplica em lugar nenhum. reserved marca uma campanha reservada, e editable aparece apenas para um solicitante limitado a pastas de telas: false significa que a campanha alcança telas fora desse escopo.

Leia uma campanha.

campaign show <id>

screenrig campaign show cmp_LUNCH

Retorna name, playlist_id, audience (a regra exata), priority, paused, reserved (true para uma campanha reservada, que só uma pessoa que pode aprovar altera), os from, until, windows, monthly, dates, except, data, interaction, covers, displays e start que estão definidos, e revision, o valor para --expect-rev em uma gravação posterior. editable aparece apenas para um solicitante limitado a pastas de telas: false significa que a campanha alcança telas fora desse escopo e é somente leitura para esse solicitante. import está presente em uma campanha criada por uma importação de programação. reach informa quantas telas o público-alvo reúne: published quando a campanha foi publicada pela última vez (criada, ou atualizada com um novo público-alvo, playlist ou estado de pausa), current e at para a contagem mais recente, e empty_groups, as folhas tag:NAME e folder:ID do público-alvo que não correspondem a nenhuma tela. Uma tag, pasta, arquivamento ou exclusão que muda a contagem é recontada em cerca de 15 segundos; campaign list também traz reach, e as notificações reach_dropped e group_empty a observam. Um id de ads campaigns list responde not_found (exit 4) aqui.

Mudar as telas de um público-alvo para uma playlist, sempre ou enquanto suas regras vigoram.

campaign create --name NAME --playlist-id ID (--tag TAG | --any-tag TAG | --screen-id ID | --folder ID | --all-screens | --audience RULE) [--from TIME] [--until TIME] [--window SPEC] [--monthly SPEC] [--date SPEC] [--except DATES] [--data KEY[:PATH[=VALUE]]] [--on-touch [IDLE_S]] [--displays N[,N]] [--start on-time|next-item] [--covers WHERE] [--priority N] [--paused] [--note TEXT]

screenrig campaign create --name "Lunch menu" --playlist-id pl_LUNCH --tag north --window mon-fri@11:00-14:00
screenrig campaign create --name "North Tower welcome" --playlist-id pl_WELCOME --folder sfd_01EXAMPLEFOLDER000000000
screenrig campaign create --name "Holiday hours" --playlist-id pl_HOLIDAY --tag Lobby --from 2026-12-20T00:00 --until 2027-01-02T00:00 --priority 10
screenrig campaign create --name "North cafes" --playlist-id pl_CAFE --audience '{"all":[{"tag":"North"},{"any":[{"tag":"Cafe"},{"tag":"Patio"}]}]}' --paused
screenrig campaign create --name "Brunch" --playlist-id pl_BRUNCH --tag Cafe --monthly 1st-sun@10:00-14:00 --except 2026-12-06
screenrig campaign create --name "Touch to browse" --playlist-id pl_MENU --screen-id scr_KIOSK --on-touch 90
screenrig campaign create --name "Holiday opening" --playlist-id pl_HOLIDAY --tag Lobby --date 2026-12-24@18:00-22:00 --start on-time
screenrig campaign create --name "Wall outputs 1 and 2" --playlist-id pl_WALL --screen-id scr_WALL --displays 1,2
screenrig campaign create --name "Room availability" --playlist-id pl_LIVE --folder sfd_01EXAMPLEFOLDER000000000 --data "crd_ROOM:/available=true"
screenrig campaign create --name "Fire exits" --playlist-id pl_EXITS --folder sfd_01EXAMPLEFOLDER000000000 --note "Fire safety"

Tags têm de 1 a 32 letras ou dígitos. DAYS é daily, um dia (mon), um intervalo (mon-fri; fri-mon atravessa o fim da semana) ou uma lista separada por vírgulas (sat,sun). Sem um horário, a janela é o dia inteiro, e um fim igual ou anterior ao início cruza a meia-noite e pertence ao dia de início. Em uma regra --audience, cada membro tem exatamente um entre all, any, tag, screen_id ou folder, os grupos se aninham em no máximo 3 níveis, um público-alvo tem no máximo 500 regras, e {"all":[]} equivale a todas as telas. O servidor recusa uma regra morta: uma data --except fora de --from e --until, um --date que começa fora delas e um --date que também é uma exceção (invalid_request, exit 8).

--data KEY vale enquanto os dados de cartão KEY existirem, --data KEY:PATH enquanto existir um valor no ponteiro RFC 6901 PATH, e --data KEY:PATH=VALUE enquanto ele for igual a VALUE, um escalar JSON (true, false, null, um número ou uma string entre aspas JSON) ou uma string simples como rain. Objetos e arrays são recusados. Dados ausentes ou expirados nunca correspondem, e um null ou false presente conta como existente. KEY:=VALUE compara o documento inteiro. Escape os dois-pontos em KEY como \: e coloque o argumento entre aspas para manter as aspas da string JSON: --data 'crd_ROOM:/status="true"'. A chave {screen.weather} lê o clima no local de cada tela (screen update ID --location LAT,LON): --data '{screen.weather}:/condition=rain'.

Após uma criação interrompida ou ambígua, execute novamente o comando idêntico dentro de 24 horas: ele reutiliza a chave de idempotência salva, e o servidor retorna a mesma campanha em vez de criar outra.

Alterar uma campanha; as telas do seu público-alvo antigo e do novo são resolvidas novamente em até um minuto.

campaign update <id> [--name NAME] [--playlist-id ID] [audience option] [--from TIME | --clear-from] [--until TIME | --clear-until] [--window SPEC | --clear-windows] [--monthly SPEC | --clear-monthly] [--date SPEC | --clear-dates] [--except DATES | --clear-except] [--data KEY[:PATH[=VALUE]] | --clear-data] [--on-touch [IDLE_S] | --clear-on-touch] [--displays N[,N] | --clear-displays] [--start WHEN] [--covers WHERE] [--priority N] [--expect-rev REVISION] [--note TEXT]

screenrig campaign update cmp_LUNCH --playlist-id pl_LUNCH2 --expect-rev 2
screenrig campaign update cmp_LUNCH --tag Lobby --window sat,sun --priority 20
screenrig campaign update cmp_LUNCH --clear-until --clear-windows
screenrig campaign update cmp_BRUNCH --monthly 2nd-sun@10:00-14:00 --except 2026-12-13,2027-01-10
screenrig campaign update cmp_BROWSE --clear-on-touch --clear-displays
screenrig campaign update cmp_ROOMS --data crd_ROOM:/available=true
screenrig campaign update cmp_ROOMS --clear-data
screenrig campaign update cmp_LUNCH --playlist-id pl_LUNCH2 --note "Safety review done"

Passe pelo menos uma alteração; apenas os campos que você passar mudam. Um novo --playlist-id é verificado como na criação. Após uma solicitação interrompida ou ambígua, execute novamente o comando idêntico: ele reutiliza a chave de idempotência salva, e o servidor retorna a atualização que já aconteceu em vez de aplicá-la novamente.

Interromper uma campanha em todas as telas sem excluí-la.

campaign pause <id> [--expect-rev REVISION] [--note TEXT]

screenrig campaign pause cmp_LUNCH
screenrig campaign pause cmp_LUNCH --note "Holiday over"

As telas que a exibiam voltam ao que exibiriam sem ela em até um minuto. campaign resume a inicia novamente.

Iniciar novamente uma campanha pausada.

campaign resume <id> [--expect-rev REVISION] [--note TEXT]

screenrig campaign resume cmp_LUNCH
screenrig campaign resume cmp_LUNCH --note "Holiday again"

Toda tela do público-alvo à qual a campanha pode se aplicar muda para a playlist da campanha em até um minuto enquanto a campanha vigora.

Excluir uma campanha.

campaign delete <id> [--expect-rev REVISION] [--note TEXT]

screenrig campaign delete cmp_LUNCH
screenrig campaign delete cmp_LUNCH --note "Replaced by the winter campaign"

A campanha não volta. Toda tela que a exibe volta ao que exibiria sem ela em até um minuto; playlists, telas e tags permanecem. campaign pause interrompe uma campanha e a mantém.

Mostrar as telas que uma campanha alcança e a situação de cada uma.

campaign screens <id> [--limit N] [--cursor CURSOR]

screenrig campaign screens cmp_LUNCH

data.counts cobre todas as telas ativas do público-alvo: audience, depois uma contagem por situação presente. data.items é uma página dessas telas em ordem de id da tela, cada uma com o status da campanha. data.next_cursor está ausente na última página. Em uma tela cujo Player resolve a própria pilha, a situação é a que essa pilha dá à campanha: uma campanha de faixa ou main é reproduzida na sua região, e uma campanha --displays, nos seus displays.

Mostrar por que cada campanha é ou não reproduzida em uma tela, agora ou em um momento escolhido.

campaign explain <screen-id> [--at TIME] [--to TIME]

screenrig campaign explain scr_LOBBY
screenrig campaign explain scr_LOBBY --at 2026-12-24T18:00 --to 2026-12-26T00:00

data.items lista todas as campanhas do projeto na ordem em que a tela as lê, cada uma com uma situação de campaign screens ou not_in_audience; uma linha blocked nomeia a correção. data.effective_playlist é a playlist que a tela reproduz agora (id, source, que é takeover, campaign, schedule, default ou folder, e entry_id, o id da campanha, da entrada de programação ou da pasta), ou null quando a tela não exibe nenhuma playlist. Não altera nada.

Com --at, data.at contém a resposta para esse momento: instant, timezone (o fuso horário efetivo da tela) e local (o instante no relógio da tela), effective_playlist (cujo until é a próxima mudança) e uma linha verdicts para o takeover, cada campanha e cada entrada de programação, na ordem em que a tela as lê.

Um veredito é won (a playlist exibida), outranked (está em vigor, e by nomeia a vencedora), not_started (antes do início), ended (depois do fim), outside_hours (dentro das datas, fora das janelas, das regras mensais ou das datas, ou em uma data de exceção; next_start diz quando volta a valer em até oito dias), conditional (está em vigor pelo horário e é reproduzida enquanto alguém usa a tela, reason interaction, ou enquanto sua condição de dados se cumpre, reason data) ou off (não se aplica, e reason diz o motivo: paused, not_in_audience, no_default_playlist, playlist_unavailable, region_not_laid_out ou stack_only). Em uma tela cujo Player resolve a própria pilha, os vereditos leem essa pilha: um nível de faixa ou main vence ou é superado na sua região, e um bloqueio de displays, nos seus displays. effective_playlist e a linha do tempo continuam sendo a página do display 1, e data.at.not_judged lista player_stack.

--to adiciona data.at.timeline, os trechos em que a playlist não muda, e timeline_truncated marca uma resposta que parou antes de --to: consulte de novo com --at definido como o to do último trecho. data.at.not_judged diz o que não é julgado: o takeover, a programação e as campanhas são lidos como estão agora, e data.items continua sendo o estado atual.

Mostrar o que criar ou alterar uma campanha faria antes de fazê-lo.

campaign preview [<id>] [--name NAME] [--playlist-id ID] [audience option] [rule flags] [clear flag] [--paused | --publish] [--calendar-from INSTANT] [--calendar-to INSTANT]

screenrig campaign preview cmp_LUNCH --tag Lobby
screenrig campaign preview cmp_LUNCH --clear-until --priority 20
screenrig campaign preview cmp_LUNCH --publish --folder sfd_TEST
screenrig campaign preview cmp_LUNCH --publish --calendar-from 2026-12-01T00:00:00Z --calendar-to 2027-01-01T00:00:00Z
screenrig campaign preview --name "Holiday hours" --playlist-id pl_HOLIDAY --tag Lobby --from 2026-12-20T00:00 --until 2027-01-02T00:00

As opções são verificadas como a gravação as verifica, então uma prévia recusa o que a gravação recusa. Com um <id>, passe pelo menos uma alteração: uma opção de campaign update, --paused ou --publish. Nada é gravado. data.gained e data.lost são {count, screen_ids} (os primeiros 500 por id): as telas que passariam a ter a campanha e agora não têm, e as que deixariam de tê-la. Uma campanha em pausa não está em nenhuma tela, então publicá-la ganha o seu público; uma edição que mantém a campanha numa tela só aparece nos calendários. data.calendar.before e data.calendar.after são os calendários de cronograma de --calendar-from a --calendar-to para as telas do público antigo e do novo, com rascunhos desenhados como níveis em pausa. --human imprime os trechos do primeiro display e os rascunhos que valeriam, e avisa quando o calendário não muda.

Tirar da pausa uma campanha em rascunho, se quiser somente para uma pasta de teste ou poucas telas de teste.

campaign publish <id> [--test-folder ID | --test-screen ID] [--expect-rev REVISION]

screenrig campaign publish cmp_LUNCH
screenrig campaign publish cmp_LUNCH --test-folder sfd_TEST
screenrig campaign publish cmp_LUNCH --test-screen scr_LOBBY,scr_CAFE --expect-rev 2

Um rascunho é uma campanha em pausa: não está em nenhuma tela até ser publicado. Sem opção de teste, a campanha alcança seu próprio público em até um minuto. Uma opção de teste substitui o público na mesma gravação, de modo que só as telas de teste mudam. O fluxo usual: campaign create --paused com o público real, campaign publish ID --test-folder FOLDER, olhar as telas de teste e depois campaign promote ID --revision N. campaign preview ID --publish mostra antes o efeito.

Colocar o público de um rascunho na campanha depois do teste.

campaign promote <id> --revision N [--expect-rev REVISION]

screenrig campaign promote cmp_LUNCH --revision 1
screenrig campaign promote cmp_LUNCH --revision 1 --expect-rev 2

O público da revisão N torna-se o da campanha em uma gravação, uma nova revisão cujo change é promoted, e cada tela do público antigo e do novo é resolvida de novo em até um minuto. A revisão N deve ser uma revisão em pausa (invalid_request a nomeia caso contrário), e a campanha deve estar ativa: uma campanha em pausa agora não tem teste para promover. Uma revisão cujo público já é o da campanha não altera nada. --expect-rev é a revisão atual da campanha, não N. Promover exige o acesso que campaign update exige.

Listar as revisões de uma campanha, a mais recente primeiro.

campaign revisions <id> [--after CURSOR]

screenrig campaign revisions cmp_LUNCH
screenrig campaign revisions cmp_LUNCH --after CURSOR

data.items contém no máximo 50 revisões, cada uma com revision, created_at, change, current, author quando conhecido e campaign, a campanha como ficou após essa gravação, com seu estado de pausa. change é created, edited (uma atualização ou uma importação de programação), restored ou promoted (uma cópia da revisão anterior que restored_from nomeia), ou baseline, a revisão que a campanha tinha quando seu histórico começou. Uma campanha cujo histórico não tem nenhuma revisão fora de pausa é um rascunho. Enquanto data.next_cursor for uma string, restam revisões mais antigas: execute o comando de novo com --after definido com esse valor. As revisões são mantidas enquanto a campanha existir e somem com a exclusão dela. Acesso somente leitura basta.

Tornar atual de novo uma revisão anterior copiando-a para a frente.

campaign restore <id> --revision N [--expect-rev REVISION]

screenrig campaign restore cmp_LUNCH --revision 3
screenrig campaign restore cmp_LUNCH --revision 3 --expect-rev 5

O nome, a playlist, o público, as regras, o região, a prioridade e o estado de pausa da revisão N tornam-se uma nova revisão cujo change é restored, verificada como campaign update é verificado: a playlist dela deve continuar existindo e estar aprovada (playlist_not_approved, exit 5). Cada tela do público antigo e do novo é resolvida de novo em até um minuto. As revisões anteriores ficam como estavam, e restaurar o conteúdo atual não muda nada. Restaurar exige o acesso que campaign update exige.