Report ed esportazioni

Riepiloghi per cartella e per tag

fleet_health, uptime, publishing e alerts raggruppano la flotta per cartella, schermo o tag su giorni UTC inclusivi. Una riga di cartella conta ogni schermo che contiene e quelli delle sue cartelle figlie, e la prima riga è l'intero progetto. I tag sono il secondo raggruppamento: uno schermo conta in ogni tag che porta.

GET /api/reports/{kind} genera un report. from e to sono giorni UTC (predefinito: gli ultimi 30 giorni); group_by è folder (predefinito), screen o tag; folder_id limita il report a una cartella e a tutto ciò che contiene, e con direct=true alla cartella e alle sue cartelle figlie oppure, raggruppato per schermo, agli schermi direttamente al suo interno; tag mantiene gli schermi con quel tag. Una riga di cartella riporta id, parent_id e depth, così un client disegna la struttura dalle righe. La disponibilità è il tempo online sul tempo registrato, e la copertura registrata indica quale parte del periodo gli schermi hanno segnalato uno stato.

La pagina Stato della dashboard presenta questi riepiloghi come cartelle di schermi: ogni cartella si apre sulle sue sottocartelle e sui suoi schermi, e ogni schermo sulla sua scheda Stato.

CSV, XLSX e PDF

Ogni route di report accetta format=csv, xlsx o pdf e risponde con un allegato con le stesse righe: i nuovi report, GET /api/uptime/daily, GET /api/screens/{id}/uptime, GET /api/screens/{id}/health/history, GET /api/health/trend, GET /api/alerts, GET /api/playback, GET /api/playback/plays, GET /api/playback/totals, GET /api/playback/completeness, i report di consegna, riempimento e spesa pubblicitaria e il report di una campagna diretta. Un report a pagine viene scritto per intero, fino a 50.000 righe; truncated indica quando contiene solo le prime righe.

Il file XLSX è un unico foglio con il titolo e il periodo sopra un'intestazione fissa, numeri come numeri e totali in grassetto. Il PDF è un rendiconto sobrio con il nome screenRIG, il progetto a cui è destinato, il titolo e il periodo, una tabella la cui intestazione si ripete a ogni pagina, i totali e i numeri di pagina, pronto da inviare. Il CSV inizia con le etichette delle colonne e neutralizza una cella di testo che un foglio di calcolo eseguirebbe come formula.

screenrig reports show fleet_health --group-by folder --format pdf --output fleet-health.pdf
screenrig reports show proof_of_play --advertiser "Acme Corp" --from 2026-10-01 --to 2026-10-31 --format pdf --output acme.pdf
screenrig project uptime --format xlsx --output uptime.xlsx
screenrig alerts list --state all --format csv --output alerts.csv

Prova di riproduzione per uno sponsor o un inserzionista

proof_of_play somma le riproduzioni delle campagne dirette del progetto. Una riproduzione conta quando lo schermo segnala che il contenuto è terminato a schermo. Indichi una campagna con campaign_id, o tutte le campagne di uno sponsor o inserzionista con advertiser (il nome esatto, senza distinzione tra maiuscole e minuscole). Ogni riga è una campagna, un file multimediale e uno schermo con le sue riproduzioni, ore riprodotte, primo e ultimo giorno e, se lo schermo ha una stima del pubblico, impressioni stimate. Il PDF è il rendiconto da inviare.

Programmazioni email

Un abbonamento a un report indica un tipo di report e i suoi filtri, una cadenza, un formato di file e i membri del progetto che lo ricevono. POST /api/report-subscriptions ne crea uno; un’organizzazione ne ha al massimo 50 in tutti i suoi progetti (report_subscription_limit_reached).

Ogni invio copre il periodo precedente, in giorni UTC: il giorno prima per un invio giornaliero, i sette giorni precedenti per uno settimanale e l'intero mese precedente per uno mensile, secondo il calendario del fuso orario della programmazione. I destinatari sono membri del progetto, verificati di nuovo a ogni invio: chiunque altro viene rifiutato quando l'abbonamento viene scritto, e un membro che se ne va, o il cui indirizzo non è verificato, smette di riceverlo. L'allegato è al massimo di 8 MiB.

Un invio che fallisce viene ripetuto dopo 15 minuti, 1 ora e 4 ore, poi attende la prossima occorrenza. L'abbonamento mostra last_status (delivered o failed), last_error, i giorni coperti dall'ultimo invio e next_run_at. POST /api/report-subscriptions/{id}/send lo invia ora per il periodo che un invio coprirebbe ora, senza spostare la programmazione, e risponde con l'abbonamento e l'esito di questo invio.

screenrig reports subscriptions create --name "Monday fleet health" --kind fleet_health \
  --cadence weekly --weekday monday --hour 7 --timezone America/Los_Angeles \
  --format pdf --recipients ann@example.com,usr_ID
screenrig reports subscriptions list
screenrig reports subscriptions send rsub_ID

La pagina Report della dashboard ha le stesse programmazioni in Programmazioni email.

Esportare un intero progetto

screenrig project export DIR scrive i dati del progetto in una directory in formati aperti. Controlla l’esito di ogni sezione prima di usare la copia per il ripristino.

Conserva gli archivi originali delle applicazioni insieme alle esportazioni per ripristinare le versioni, incluse quelle fissate da vecchie playlist. Le omissioni di contenuto compaiono nella sezione dei file delle applicazioni e impostano data.complete:false con export_application_content_omitted, anche con --no-media. Una nuova esecuzione aggiorna i metadati.

I dati K/V delle applicazioni vengono copiati integralmente sia con --no-media sia con --since. Se la lettura dell’elenco K/V o di un valore non riesce, la sezione applications riporta un errore con export_section_failed e imposta data.complete:false. Risolvi l’errore di lettura e ripeti l’esportazione per aggiornare la copia.

Le credenziali non sono mai nella copia: la chiave di firma e l'indirizzo di ricezione di un webhook, la credenziale di chat o pager di una notifica e i segreti di una fonte di dati ne restano fuori (il file mantiene l'origine del ricevitore e i nomi dei segreti). Rieseguire è sicuro: i file JSON vengono riscritti per intero, un file multimediale già completo viene mantenuto e un download parziale riprende dai byte che ha. Ogni file multimediale viene verificato rispetto allo SHA-256 che il progetto conserva prima di essere mantenuto. --no-media salta i file multimediali e --since DAY avvia i dati CSV e il registro eventi in un giorno. Ogni richiesta è una richiesta API fatturata e i download dei contenuti sono egress.