API Campagne

Elenca le campagne del progetto in ordine di precedenza (al massimo 100), l’ordine in cui la risoluzione le legge. reserved è presente su ogni campagna.

Un chiamante limitato agli schermi (docs/screen-scope.md) vede ogni campagna, con editable true solo quando l’intero pubblico è dentro il suo ambito (una foglia tag e la regola radice per ogni schermo non lo sono mai; una regola all richiede un figlio contenuto, una regola any ogni figlio) e il chiamante può cambiare ciò che viene riprodotto.

Crea una campagna: ogni schermo nel suo audience passa a playlist_id finché from, until e windows valgono nel fuso orario dello schermo (screenrig.schedule/v1; ometti tutti e tre per sempre), e torna indietro quando smettono di valere.

Uno schermo risolve la sua playlist come takeover, poi la prima campagna che si applica in ordine di precedenza (priority, prima la più alta, poi la più recente), poi il suo programma playlist, poi la sua playlist predefinita. Una campagna si applica solo a uno schermo con una playlist predefinita; una con from, until o windows richiede il fuso orario dello schermo.

La playlist deve esistere ed essere approvata (playlist_not_approved). Gli schermi cambiano entro un minuto; GET /api/campaigns/{id}/screens mostra la situazione di ogni schermo. Un’organizzazione ha al massimo 100 campagne in tutti i suoi progetti (campaign_limit_reached).

Aggiunge campaign.created. reserved true riserva la campagna, e solo una persona che può approvare lo imposta (reserved_item per un agente, un client di servizio o chiunque altro), aggiungendo campaign.reserved_changed.

Un chiamante limitato agli schermi (docs/screen-scope.md) crea una campagna solo per un pubblico dentro il suo ambito (foglie folder e screen_id; nessun tag, nessuna regola per ogni schermo), altrimenti outside_screen_scope, e solo come persona che può approvare (approver_required).

Una campagna il cui pubblico raggiunge uno schermo protetto è una revisione protected_change decisa da un secondo approvatore (202 pending_review) a ogni livello di accesso. reserved true rientra nelle cartelle protette e paused true su una nuova campagna (una bozza) nel controllo delle modifiche alla programmazione, entrambi parte del piano Enterprise; un progetto il cui piano ne è privo viene rifiutato con feature_not_in_plan (402).

Che cosa cambierebbe una scrittura di campagna, senza eseguirla. Con id, body è il corpo PATCH di quella campagna; senza, è il corpo POST di una nuova. Il corpo viene verificato come lo verifica la scrittura (una regola di pubblico, una finestra, una playlist non approvata, una cartella di schermi che il progetto non ha).

La risposta elenca gli schermi che otterrebbero la campagna nel loro stack e quelli che la perderebbero (count e i primi 500 id di schermo), e il calendario di programmazione degli schermi del vecchio e del nuovo pubblico così com’è (before) e come sarebbe (after) da from a to (predefinito: una settimana da adesso; al massimo 93 giorni), raggruppato come lo raggruppa GET /api/schedule/calendar.

Una campagna in pausa non è su nessuno stack, quindi pubblicarne una le fa ottenere il suo pubblico; una modifica che mantiene la campagna sullo stack di uno schermo non guadagna né perde nulla e compare nei calendari. Accesso in lettura: non viene scritto nulla.

Una campagna. reserved è sempre presente; editable è presente per un chiamante limitato agli schermi (vedi listCampaigns).

Modifica i membri che il corpo imposta; null azzera from, until o windows. paused true ferma la campagna su ogni schermo e false la riprende. Una campagna in pausa è una bozza: non è sullo stack di nessuno schermo, e una scrittura che la lascia in pausa non rivaluta alcuno schermo.

Pubblicarla per un test è questo PATCH con paused false e un pubblico che è una cartella di test o pochi schermi; POST /api/campaigns/{id}/promote copia poi quel pubblico su quello reale. Ogni schermo del vecchio e del nuovo pubblico viene rivalutato entro un minuto. Aggiunge campaign.updated. If-Match protegge la revisione.

Ogni scrittura viene memorizzata nella cronologia della campagna (GET /api/campaigns/{id}/revisions). campaign.updated. If-Match protegge la revisione. reserved imposta o azzera il flag reserved (una campagna riservata viene modificata, messa in pausa o resa non riservata solo da una persona che può approvare: altrimenti reserved_item); un cambio aggiunge campaign.reserved_changed.

Un chiamante limitato agli schermi (docs/screen-scope.md) modifica una campagna solo quando il suo pubblico memorizzato e quello nuovo sono dentro il suo ambito (outside_screen_scope; altrimenti per lui è di sola lettura).

Una campagna che raggiunge uno schermo protetto è una revisione protected_change decisa da un secondo approvatore (202 pending_review). reserved true su una campagna non riservata rientra nelle cartelle protette, che il piano Enterprise include; un progetto il cui piano ne è privo viene rifiutato con feature_not_in_plan (402).

Mettere in pausa o riprendere una campagna, e modificare o rilasciare una campagna riservata, sono operazioni disponibili in ogni piano.

Elimina la campagna e la sua cronologia delle revisioni. Ogni schermo che la mostra torna entro un minuto a ciò che mostrerebbe senza di essa. Aggiunge campaign.deleted. If-Match protegge la revisione. Una campagna riservata viene eliminata solo da una persona che può approvare (reserved_item).

Un chiamante limitato agli schermi (docs/screen-scope.md) elimina una campagna solo quando il suo pubblico è dentro il suo ambito (outside_screen_scope). Una campagna che raggiunge uno schermo protetto è una revisione protected_change (202 pending_review) decisa da un secondo approvatore.

Le revisioni della campagna, dalla più recente: la campagna come memorizzata dopo ogni scrittura da parte di una persona, di un agente o di un’importazione di programmazione (una creazione, un aggiornamento, una promozione, un ripristino), con il tipo di modifica e chi l’ha fatta.

La cronologia inizia con la revisione che una campagna aveva quando la cronologia delle revisioni è stata registrata per la prima volta: fino alla sua scrittura successiva l’elenco contiene solo quella revisione, con change baseline. Una campagna la cui cronologia non contiene alcuna revisione con paused false è una bozza. Le revisioni vengono conservate finché esiste la campagna e vanno via con essa.

Al massimo 50 per pagina; next_cursor finché ne restano altre, null nell’ultima pagina.

Rende di nuovo corrente una revisione precedente copiandola in avanti con la stessa scrittura di PATCH: il suo nome, la playlist, il pubblico, la regola, il posizionamento, la priorità e paused diventano una nuova revisione (change restored, restored_from la revisione copiata), verificata come lo è un aggiornamento (la sua playlist deve ancora esistere ed essere approvata), e ogni schermo del vecchio e del nuovo pubblico viene rivalutato, a meno che la campagna fosse in pausa e resti in pausa.

Le revisioni precedenti restano com’erano. If-Match è obbligatorio e indica la revisione corrente (invalid_request se assente, revision_conflict se obsoleta). Una revisione il cui contenuto è quello corrente non cambia nulla e risponde con la campagna corrente. Lo stesso accesso di PATCH.

Pubblica un test. Una pubblicazione di test è un PATCH di una bozza con paused false e un pubblico che è una cartella di test o pochi schermi; promote copia poi il pubblico di revision (la revisione della bozza stessa, in pausa) sulla campagna in un’unica scrittura (change promoted, restored_from la revisione copiata) e ogni schermo del vecchio e del nuovo pubblico viene rivalutato.

Rifiutato (invalid_request, che nomina revision) quando quella revisione non era in pausa, perché non è una bozza, e quando la campagna è ora in pausa, perché non c’è alcun test da promuovere. If-Match è obbligatorio e indica la revisione corrente. Una revisione il cui pubblico è quello corrente non cambia nulla. Lo stesso accesso di PATCH.

Promuovere rientra nel controllo delle modifiche alla programmazione, che il piano Enterprise include; un progetto il cui piano ne è privo viene rifiutato con feature_not_in_plan (402). La cronologia delle revisioni, il ripristino e le anteprime sono disponibili in ogni piano.

La copertura della campagna. counts riguarda ogni schermo live nel suo audience (audience, poi un conteggio per stato); items è una pagina di quegli schermi in ordine di id schermo con lo stato della campagna su ciascuno (vedi CampaignStatus).

Un chiamante limitato agli schermi (docs/screen-scope.md) vede e conta solo gli schermi del pubblico dentro il suo ambito; conteggi e paginazione riguardano quell’insieme.