Campagnes : commandes CLI

Lister les campagnes du projet dans l’ordre où les écrans les lisent.

campaign list

Aucun paramètre.

screenrig campaign list

data.items contient au maximum 100 campagnes, les priorités les plus élevées d’abord et les plus récentes d’abord au sein d’une même priorité. Chacune porte les champs que renvoie campaign show, avec reach une fois comptée. Une campagne en pause est listée et ne s’applique nulle part. reserved marque une campagne réservée, et editable n’apparaît que pour un appelant limité à des dossiers d’écrans : false signifie que la campagne atteint des écrans hors de ce périmètre.

Lire une campagne.

campaign show <id>

screenrig campaign show cmp_LUNCH

Retourne name, playlist_id, audience (la règle exacte), priority, paused, reserved (true pour une campagne réservée, que seule une personne pouvant approuver modifie), les from, until, windows, monthly, dates, except, data, interaction, covers, displays et start qui sont définis, et revision, la valeur pour --expect-rev lors d’une écriture ultérieure. editable n’apparaît que pour un appelant limité à des dossiers d’écrans : false signifie que la campagne atteint des écrans hors de ce périmètre et est en lecture seule pour cet appelant. import est présent sur une campagne créée par une importation d’horaires. reach indique combien d’écrans l’audience couvre : published à la dernière publication de la campagne (créée, ou mise à jour avec une nouvelle audience, liste de lecture ou état de pause), current et at pour le dernier compte, et empty_groups, les feuilles tag:NAME et folder:ID de l’audience qui ne correspondent à aucun écran. Une étiquette, un dossier, un archivage ou une suppression qui change le compte est recompté en environ 15 secondes ; campaign list porte aussi reach, et les notifications reach_dropped et group_empty le surveillent. Un identifiant de ads campaigns list répond not_found (sortie 4) ici.

Faire basculer les écrans d’une audience vers une liste de lecture, en tout temps ou tant que ses règles sont en vigueur.

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"

Les étiquettes comptent de 1 à 32 lettres ou chiffres. DAYS est daily, un jour (mon), une plage (mon-fri ; fri-mon traverse la fin de la semaine) ou une liste séparée par des virgules (sat,sun). Sans heure, la fenêtre couvre toute la journée, et une fin à ou avant le début traverse minuit et appartient au jour de début. Dans une règle --audience, chaque membre a exactement l’un de all, any, tag, screen_id ou folder, les groupes s’imbriquent sur 3 niveaux au plus, une audience a au plus 500 règles, et {"all":[]} désigne chaque écran. Le serveur refuse une règle morte : une date --except hors de --from et --until, un --date qui commence en dehors d’elles, et un --date qui est aussi une exception (invalid_request, sortie 8).

--data KEY tient tant que les données de carte KEY existent, --data KEY:PATH tant qu’une valeur existe au pointeur RFC 6901 PATH, et --data KEY:PATH=VALUE tant qu’elle est égale à VALUE, un scalaire JSON (true, false, null, un nombre ou une chaîne entre guillemets JSON) ou une chaîne brute comme rain. Les objets et les tableaux sont refusés. Des données absentes ou expirées ne correspondent jamais, et un null ou un false présent compte comme existant. KEY:=VALUE compare le document entier. Échappez un deux-points dans KEY avec \:, et mettez l’argument entre guillemets pour conserver les guillemets de la chaîne JSON : --data 'crd_ROOM:/status="true"'. La clé {screen.weather} lit la météo à l’emplacement de chaque écran (screen update ID --location LAT,LON) : --data '{screen.weather}:/condition=rain'.

Après une création interrompue ou ambiguë, relancez la même commande dans les 24 heures : elle réutilise la clé d’idempotence enregistrée, et le serveur renvoie la même campagne au lieu d’en créer une autre.

Modifier une campagne ; les écrans de son ancienne et de sa nouvelle audience résolvent à nouveau dans la minute.

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"

Passez au moins un changement ; seuls les champs que vous passez changent. Un nouveau --playlist-id est vérifié comme à la création. Après une requête interrompue ou ambiguë, relancez la même commande : elle réutilise la clé d’idempotence enregistrée, et le serveur renvoie la mise à jour qui a déjà eu lieu au lieu de l’appliquer à nouveau.

Arrêter une campagne sur chaque écran sans la supprimer.

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

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

Les écrans qui l’affichaient reviennent, dans la minute, à ce qu’ils afficheraient sans elle. campaign resume la redémarre.

Redémarrer une campagne en pause.

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

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

Chaque écran de l’audience auquel la campagne peut s’appliquer bascule vers la liste de lecture de la campagne dans la minute tant que celle-ci est en vigueur.

Supprimer une campagne.

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 campagne ne revient pas. Chaque écran qui l’affiche revient, dans la minute, à ce qu’il afficherait sans elle ; les listes de lecture, les écrans et les étiquettes restent. campaign pause arrête une campagne et la conserve.

Afficher les écrans qu’une campagne atteint et l’état de chacun.

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

screenrig campaign screens cmp_LUNCH

data.counts couvre chaque écran actif de l’audience : audience, puis un compte par état présent. data.items est une page de ces écrans dans l’ordre des identifiants d’écran, chacun avec le status de la campagne. data.next_cursor est absent de la dernière page. Sur un écran dont le lecteur résout sa propre pile, l’état est celui que cette pile donne à la campagne : une campagne en bandeau ou main joue dans sa région, et une campagne --displays sur ses afficheurs.

Afficher pourquoi chaque campagne joue ou non sur un écran, maintenant ou à un moment choisi.

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 liste chaque campagne du projet dans l’ordre où l’écran les lit, chacune avec un état issu de campaign screens ou not_in_audience ; une ligne blocked nomme la correction. data.effective_playlist est la liste de lecture que l’écran joue maintenant (id, source, qui vaut takeover, campaign, schedule, default ou folder, et entry_id, l’identifiant de la campagne, de l’entrée de programmation ou du dossier), ou null quand l’écran n’affiche aucune liste de lecture. Rien n’est modifié.

Avec --at, data.at contient la réponse pour ce moment : instant, timezone (le fuseau horaire effectif de l’écran) et local (l’instant sur l’horloge de l’écran), effective_playlist (dont until est le prochain changement) et une ligne verdicts pour la prise de contrôle, chaque campagne et chaque entrée de programmation, dans l’ordre où l’écran les lit.

Un verdict est won (la liste de lecture affichée), outranked (elle est en vigueur, et by nomme le gagnant), not_started (avant son début), ended (après sa fin), outside_hours (dans ses dates, hors de ses fenêtres, de ses règles mensuelles ou de ses dates, ou à une date d’exception ; next_start dit quand elle est de nouveau en vigueur dans les huit jours), conditional (elle est en vigueur selon l’horaire et joue tant que quelqu’un utilise l’écran, reason interaction, ou tant que sa condition de données est remplie, reason data) ou off (elle ne s’applique pas, et reason dit pourquoi : paused, not_in_audience, no_default_playlist, playlist_unavailable, region_not_laid_out ou stack_only). Sur un écran dont le Player résout sa propre pile, les verdicts lisent cette pile : un niveau en bandeau ou main l’emporte ou est devancé dans sa région, et un verrou d’afficheurs sur ses afficheurs. effective_playlist et la chronologie restent la page de l’afficheur 1, et data.at.not_judged liste player_stack.

--to ajoute data.at.timeline, les périodes pendant lesquelles la liste de lecture ne change pas, et timeline_truncated signale une réponse arrêtée avant --to : relancez la requête avec --at réglé sur le to de la dernière période. data.at.not_judged dit ce qui n’est pas jugé : la prise de contrôle, la programmation et les campagnes sont lues telles qu’elles sont maintenant, et data.items reste l’état actuel.

Montrer ce que ferait la création ou la modification d’une campagne avant de la faire.

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

Les options sont vérifiées comme l’écriture les vérifie, donc un aperçu refuse ce que refuse l’écriture. Avec un <id>, passez au moins un changement : une option de campaign update, --paused ou --publish. Rien n’est écrit. data.gained et data.lost sont {count, screen_ids} (les 500 premiers par identifiant) : les écrans qui porteraient la campagne et ne la portent pas maintenant, et ceux qui ne la porteraient plus. Une campagne en pause n’est sur aucun écran, donc la publier gagne son audience ; une modification qui garde la campagne sur un écran ne se voit que dans les calendriers. data.calendar.before et data.calendar.after sont les calendriers d’horaires de --calendar-from à --calendar-to pour les écrans de l’ancienne et de la nouvelle audience, avec les brouillons dessinés comme niveaux en pause. --human affiche les plages du premier affichage et les brouillons qui s’appliqueraient, et indique quand le calendrier ne change pas.

Sortir une campagne brouillon de la pause, si l’on veut seulement pour un dossier de test ou quelques écrans de test.

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

Un brouillon est une campagne en pause : elle n’est sur aucun écran tant qu’elle n’est pas publiée. Sans option de test, la campagne atteint sa propre audience en moins d’une minute. Une option de test remplace l’audience dans la même écriture, de sorte que seuls les écrans de test changent. Le déroulement habituel : campaign create --paused avec l’audience réelle, campaign publish ID --test-folder FOLDER, regarder les écrans de test, puis campaign promote ID --revision N. campaign preview ID --publish montre d’abord l’effet.

Appliquer à la campagne l’audience d’un brouillon après son test.

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

L’audience de la révision N devient celle de la campagne en une écriture, une nouvelle révision dont change est promoted, et chaque écran de l’ancienne et de la nouvelle audience est réévalué en moins d’une minute. La révision N doit être une révision en pause (invalid_request la nomme sinon), et la campagne doit être active : une campagne en pause maintenant n’a aucun test à promouvoir. Une révision dont l’audience est déjà celle de la campagne ne change rien. --expect-rev est la révision courante de la campagne, et non N. La promotion exige l’accès qu’exige campaign update.

Lister les révisions d’une campagne, la plus récente d’abord.

campaign revisions <id> [--after CURSOR]

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

data.items contient au plus 50 révisions, chacune avec revision, created_at, change, current, author lorsqu’il est connu et campaign, la campagne telle qu’elle était après cette écriture, avec son état de pause. change est created, edited (une mise à jour ou une importation d’horaires), restored ou promoted (une copie de la révision antérieure que nomme restored_from), ou baseline, la révision que la campagne avait quand son historique a commencé. Une campagne dont l’historique n’a aucune révision hors pause est un brouillon. Tant que data.next_cursor est une chaîne, des révisions plus anciennes restent : relancez la commande avec --after réglé à cette valeur. Les révisions sont conservées aussi longtemps que la campagne et partent avec sa suppression. L’accès en lecture seule suffit.

Rendre de nouveau courante une révision antérieure en la copiant vers l’avant.

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

Le nom, la liste de lecture, l’audience, les règles, le région, la priorité et l’état de pause de la révision N deviennent une nouvelle révision dont change est restored, vérifiée comme l’est campaign update : sa liste de lecture doit toujours exister et être approuvée (playlist_not_approved, sortie 5). Chaque écran de l’ancienne et de la nouvelle audience est réévalué en moins d’une minute. Les révisions antérieures restent telles quelles, et restaurer le contenu actuel ne change rien. La restauration exige l’accès qu’exige campaign update.