Campagne: comandi CLI

Elenca le campagne del progetto nell’ordine in cui gli schermi le leggono.

campaign list

Nessun parametro.

screenrig campaign list

data.items contiene al massimo 100 campagne, prima quelle con la priorità più alta e, a parità di priorità, le più recenti per prime. Ognuna riporta i campi restituiti da campaign show, con reach una volta conteggiata. Una campagna in pausa è elencata e non si applica da nessuna parte. reserved segnala una campagna riservata, e editable compare solo per un chiamante limitato a cartelle di schermi: false significa che la campagna raggiunge schermi al di fuori di quell’ambito.

Leggi una campagna.

campaign show <id>

screenrig campaign show cmp_LUNCH

Restituisce name, playlist_id, audience (la regola esatta), priority, paused, reserved (true per una campagna riservata, che solo una persona che può approvare modifica), i from, until, windows, monthly, dates, except, data, interaction, covers, displays e start impostati, e revision, il valore per --expect-rev in una scrittura successiva. editable compare solo per un chiamante limitato a cartelle di schermi: false significa che la campagna raggiunge schermi fuori da quell’ambito ed è di sola lettura per quel chiamante. import è presente su una campagna creata da un’importazione della programmazione. reach riporta quanti schermi il pubblico comprende: published quando la campagna è stata pubblicata l'ultima volta (creata, o aggiornata con un nuovo pubblico, una nuova playlist o uno stato di pausa), current e at per il conteggio più recente, e empty_groups, le foglie tag:NAME e folder:ID del pubblico che non corrispondono ad alcuno schermo. Un tag, una cartella, un'archiviazione o un'eliminazione che cambia il conteggio viene ricalcolato entro circa 15 secondi; campaign list riporta anche reach, e le notifiche reach_dropped e group_empty lo controllano. Un id da ads campaigns list risponde qui con not_found (exit 4).

Commuta gli schermi di un pubblico su una playlist, sempre o finché sono in vigore le sue regole.

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"

I tag sono da 1 a 32 lettere o cifre. DAYS è daily, un giorno (mon), un intervallo (mon-fri; fri-mon supera la fine della settimana) o un elenco separato da virgole (sat,sun). Senza un orario la finestra è l’intera giornata, e una fine uguale o precedente all’inizio attraversa la mezzanotte e appartiene al giorno di inizio. In una regola --audience ogni membro ha esattamente uno tra all, any, tag, screen_id o folder, i gruppi si annidano al massimo a 3 livelli, un pubblico ha al massimo 500 regole e {"all":[]} è ogni schermo. Il server rifiuta una regola morta: una data --except fuori da --from e --until, un --date che inizia fuori da esse e un --date che è anche un’eccezione (invalid_request, exit 8).

--data KEY vale finché i dati di scheda KEY esistono, --data KEY:PATH finché esiste un valore al puntatore RFC 6901 PATH, e --data KEY:PATH=VALUE finché è uguale a VALUE, uno scalare JSON (true, false, null, un numero o una stringa tra virgolette JSON) o una stringa semplice come rain. Oggetti e array vengono rifiutati. I dati mancanti o scaduti non corrispondono mai, e un null o false presente conta come esistente. KEY:=VALUE confronta l’intero documento. Esegui l’escape dei due punti in KEY come \: e racchiudi l’argomento tra virgolette per mantenere le virgolette della stringa JSON: --data 'crd_ROOM:/status="true"'. La chiave {screen.weather} legge il meteo nella posizione di ogni schermo (screen update ID --location LAT,LON): --data '{screen.weather}:/condition=rain'.

Dopo una creazione interrotta o ambigua, riesegui lo stesso comando entro 24 ore: riutilizza la chiave di idempotenza salvata e il server restituisce la stessa campagna invece di crearne un’altra.

Modifica una campagna; gli schermi del suo vecchio e del suo nuovo pubblico vengono rivalutati entro un 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"

Passa almeno una modifica; cambiano solo i campi passati. Un nuovo --playlist-id è verificato come in creazione. Dopo una richiesta interrotta o ambigua, riesegui lo stesso comando: riutilizza la chiave di idempotenza salvata e il server restituisce l’aggiornamento già avvenuto invece di applicarlo di nuovo.

Ferma una campagna su ogni schermo senza eliminarla.

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

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

Gli schermi che la mostravano tornano a ciò che mostrerebbero senza di essa entro un minuto. campaign resume l’avvia di nuovo.

Avvia di nuovo una campagna in pausa.

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

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

Ogni schermo del pubblico a cui la campagna può applicarsi passa alla sua playlist entro un minuto finché la campagna è in vigore.

Elimina una campagna.

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

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

La campagna non ritorna. Ogni schermo che la mostra torna a ciò che mostrerebbe senza di essa entro un minuto; playlist, schermi e tag restano. campaign pause ferma una campagna e la conserva.

Mostra gli schermi raggiunti da una campagna e lo stato di ciascuno.

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

screenrig campaign screens cmp_LUNCH

data.counts copre ogni schermo live del pubblico: audience, poi un conteggio per ogni stato presente. data.items è una pagina di quegli schermi in ordine di id schermo, ciascuno con il status della campagna. data.next_cursor è assente nell’ultima pagina. Su uno schermo il cui lettore risolve il proprio stack, lo stato è quello che lo stack assegna alla campagna: una campagna a fascia o main viene riprodotta nella sua regione, e una campagna --displays sui suoi display.

Mostra perché ogni campagna viene riprodotta o meno su uno schermo, ora o in un momento scelto.

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 elenca ogni campagna del progetto nell’ordine in cui lo schermo le legge, ciascuna con uno stato da campaign screens o not_in_audience; una riga blocked indica la correzione. data.effective_playlist è la playlist che lo schermo riproduce ora (id, source, che è takeover, campaign, schedule, default o folder, e entry_id, l’id della campagna, della voce di programmazione o della cartella), o null quando lo schermo non mostra alcuna playlist. Non cambia nulla.

Con --at, data.at contiene la risposta per quel momento: instant, timezone (il fuso orario effettivo dello schermo) e local (l’istante sull’orologio dello schermo), effective_playlist (il cui until è il prossimo cambiamento) e una riga verdicts per il takeover, ogni campagna e ogni voce di programmazione, nell’ordine in cui lo schermo le legge.

Un verdetto è won (la playlist mostrata), outranked (è in vigore, e by indica la vincitrice), not_started (prima dell’inizio), ended (dopo la fine), outside_hours (dentro le date, fuori dalle finestre, dalle regole mensili o dalle date, o in una data di eccezione; next_start indica quando torna in vigore entro otto giorni), conditional (è in vigore per orario e viene riprodotta mentre qualcuno usa lo schermo, reason interaction, o mentre la sua condizione sui dati è soddisfatta, reason data) o off (non si applica, e reason dice perché: paused, not_in_audience, no_default_playlist, playlist_unavailable, region_not_laid_out o stack_only). Su uno schermo il cui Player risolve il proprio stack, i verdetti leggono quello stack: un livello a fascia o main vince o viene superato nella sua regione, e un blocco dei display sui suoi display. effective_playlist e la sequenza temporale restano la pagina del display 1, e data.at.not_judged elenca player_stack.

--to aggiunge data.at.timeline, gli intervalli in cui la playlist non cambia, e timeline_truncated segnala una risposta che si è fermata prima di --to: interroga di nuovo con --at impostato sul to dell’ultimo intervallo. data.at.not_judged indica ciò che non viene giudicato: il takeover, il programma e le campagne sono letti come sono ora, e data.items resta lo stato attuale.

Mostrare cosa farebbe creare o modificare una campagna prima di farlo.

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

Le opzioni vengono controllate come le controlla la scrittura, quindi un’anteprima rifiuta ciò che la scrittura rifiuta. Con un <id>, passa almeno una modifica: un’opzione di campaign update, --paused o --publish. Non viene scritto nulla. data.gained e data.lost sono {count, screen_ids} (i primi 500 per id): gli schermi che porterebbero la campagna e ora non la portano, e quelli che non la porterebbero più. Una campagna in pausa non è su alcuno schermo, quindi pubblicarla ne guadagna il pubblico; una modifica che mantiene la campagna su uno schermo si vede solo nei calendari. data.calendar.before e data.calendar.after sono i calendari dei programmi da --calendar-from a --calendar-to per gli schermi del vecchio e del nuovo pubblico, con le bozze disegnate come livelli in pausa. --human stampa i tratti del primo display e le bozze che sarebbero in vigore, e dice quando il calendario non cambia.

Togliere la pausa a una campagna in bozza, volendo solo per una cartella di prova o pochi schermi di prova.

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

Una bozza è una campagna in pausa: non è su alcuno schermo finché non viene pubblicata. Senza opzione di prova, la campagna raggiunge il suo pubblico entro un minuto. Un’opzione di prova sostituisce il pubblico nella stessa scrittura, così cambiano solo gli schermi di prova. Il flusso abituale: campaign create --paused con il pubblico reale, campaign publish ID --test-folder FOLDER, guardare gli schermi di prova, poi campaign promote ID --revision N. campaign preview ID --publish mostra prima l’effetto.

Mettere il pubblico di una bozza sulla campagna dopo la sua prova.

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

Il pubblico della revisione N diventa quello della campagna in una scrittura, una nuova revisione il cui change è promoted, e ogni schermo del vecchio e del nuovo pubblico si risolve di nuovo entro un minuto. La revisione N deve essere una revisione in pausa (altrimenti invalid_request la nomina), e la campagna deve essere attiva: una campagna ora in pausa non ha alcuna prova da promuovere. Una revisione il cui pubblico è già quello della campagna non cambia nulla. --expect-rev è la revisione corrente della campagna, non N. La promozione richiede l’accesso richiesto da campaign update.

Elenca le revisioni di una campagna, la più recente per prima.

campaign revisions <id> [--after CURSOR]

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

data.items contiene al massimo 50 revisioni, ciascuna con revision, created_at, change, current, author quando noto e campaign, la campagna com’era dopo quella scrittura, con il suo stato di pausa. change è created, edited (un aggiornamento o un’importazione della programmazione), restored o promoted (una copia della revisione precedente indicata da restored_from), oppure baseline, la revisione che la campagna aveva quando è iniziata la sua cronologia. Una campagna la cui cronologia non ha alcuna revisione non in pausa è una bozza. Finché data.next_cursor è una stringa, restano revisioni più vecchie: esegui di nuovo il comando con --after impostato su quel valore. Le revisioni restano finché esiste la campagna e vanno via con la sua eliminazione. Basta l’accesso in sola lettura.

Rendere di nuovo corrente una revisione precedente copiandola in avanti.

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

Nome, playlist, pubblico, regole, regione, priorità e stato di pausa della revisione N diventano una nuova revisione il cui change è restored, controllata come lo è campaign update: la sua playlist deve ancora esistere ed essere approvata (playlist_not_approved, exit 5). Ogni schermo del vecchio e del nuovo pubblico si risolve di nuovo entro un minuto. Le revisioni precedenti restano com’erano, e ripristinare il contenuto corrente non cambia nulla. Il ripristino richiede l’accesso richiesto da campaign update.