API di digital signage per sviluppatori

Uno script, un lavoro CI o un server accede come client di servizio. Chiedi all’endpoint dei token un token di accesso da 15 minuti, poi invialo come bearer. Questo elenca gli schermi del progetto:

# Get a token with a service client's id and secret.
curl -s https://api.screenrig.ai/oauth/token \
  -u "$SCREENRIG_CLIENT_ID:$SCREENRIG_CLIENT_SECRET" \
  -d grant_type=client_credentials

# Put the access_token it returns in $TOKEN, then list the screens.
curl -s https://api.screenrig.ai/api/screens \
  -H "Authorization: Bearer $TOKEN"

Non esiste un refresh token: chiedine uno nuovo quando il token scade. Una chiave registrata può accedere al posto di un segreto, e Client di servizio mostra entrambi.

Un unico contratto OpenAPI descrive ogni chiamata. Ogni area ha la propria pagina di riferimento con i campi di ogni operazione, un modello di richiesta e le sue risposte.

Il riferimento API elenca ogni gruppo, inclusi avvisi, single sign-on e provisioning degli utenti (SCIM).

Ogni chiamante accede con la propria sessione, e una persona approva ogni agente e app e crea ogni client di servizio. I token di accesso vanno in un’intestazione Authorization: Bearer e durano 15 minuti.

• Un server, uno script o un lavoro CI usa un client di servizio con una chiave o un segreto e chiede un nuovo token quando uno scade. Un client può avere fino a due chiavi e due segreti, così puoi ruotarli senza interruzioni, e un’organizzazione può avere fino a 50 client di servizio attivi.
• Un agente esegue screenrig login, e una persona approva il codice nella dashboard. Un nuovo agente senza account inizia con screenrig agent enroll.
• Un’app collegata come Claude, ChatGPT o Grok apre la pagina di consenso di screenRIG.

La persona sceglie quanto può fare il chiamante e in quali aree: schermi, contenuti, playlist, pubblicità, report e progetto.

• Solo lettura elenca e legge.
• Proponi carica anche contenuti multimediali e propone modifiche. La chiamata riesce con un link di revisione, e nulla viene riprodotto finché una persona non approva la modifica nella dashboard.
• Gestisci modifica, pubblica e spende anche.

Una persona può terminare qualsiasi sessione dalla pagina Accesso della dashboard, e i suoi token smettono di funzionare nel giro di pochi secondi. Autenticazione e Client di servizio trattano chiavi, rotazione ed errori.

Ogni interfaccia raggiunge lo stesso progetto, con lo stesso isolamento del progetto, gli stessi limiti di frequenza, la stessa idempotenza e gli stessi controlli di revisione. Il server remoto copre le chiamate in stile API. I passaggi che spostano file o segreti restano nel CLI.

Il CLI screenrig incapsula l’API per shell, cron job e agenti da terminale. Ogni comando stampa un’unica busta JSON (ok, poi data o error, con un request_id) ed esce con un codice per ogni esito, come 4 per non trovato, 5 per un conflitto, 6 per una revisione obsoleta e 7 quando si è limitati dalla frequenza. Il plugin ufficiale lo include.

screenrig screen list --tag Lobby
screenrig screen assign --tag Lobby --playlist-id pl_01EXAMPLEPLAYLIST000000

Aggiungi --idempotency-key per ripetere una scrittura in sicurezza. Il riferimento del CLI elenca ogni comando.

Un’app kiosk è una pagina web statica. Quando la pubblichi, il packer aggiunge il runtime, così la pagina ottiene window.screenrig senza alcun passaggio di build. La pagina può attendere di essere attiva, inviare eventi con nome e leggere un archivio chiave/valore le cui modifiche raggiungono ogni schermo che esegue l’app nel giro di pochi secondi. Software kiosk per Android e BrightSign ne registra una creata, toccata e riformulata in chat, e il riferimento dell’SDK elenca tutto ciò che la pagina può chiamare.

screenRIG gestisce un server MCP remoto all’indirizzo https://api.screenrig.ai/mcp. Claude, ChatGPT o Grok si collegano con OAuth: una persona approva l’app, sceglie il progetto e Solo lettura, Proponi o Gestisci, e l’app ottiene strumenti per schermi, playlist, contenuti multimediali, programmazioni, webhook e report. Il plugin ufficiale resta il flusso completo, perché carica file e impacchetta app sulla tua macchina. Il riferimento del server MCP contiene i dettagli, e Server MCP a confronto mette il server a confronto con altri prodotti.

Preferisci partire dall’assistente che usi? Controlla una TV con ChatGPT, Claude, Gemini o Grok mostra ogni percorso di installazione, e Come può il mio agente AI mettere contenuti su una TV? li copre tutti. Digital signage AI elenca richieste di esempio.

Le risposte dell’agente, una per una. L’esecuzione è reale: 26 ottobre 2026, nell’ambiente di staging di screenRIG. Il conto alla rovescia e la sua etichetta sono contenuti dimostrativi.

La revisione di uno schermo è il suo ETag. Rinviala come condizione, e la scrittura viene applicata solo se nessuno ha modificato lo schermo nel frattempo:

curl -X PATCH "$API/api/screens/$SCREEN" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H 'If-Match: W/"21"' \
  -d '{"playlist_id": "'"$PLAYLIST"'"}'

La prima volta è stato applicato e lo schermo è passato alla revisione 22. Inviato di nuovo con la vecchia revisione, è stato rifiutato, e la risposta (ridotta qui) indicava quella attuale, così il client può rileggere e riprovare:

{"errors": [{"status": 412, "code": "revision_conflict", "current_revision": 22}]}

Ogni errore riporta un codice stabile, un link alla sua descrizione e un suggerimento su cosa fare dopo. Un ID mancante risponde 404 con un suggerimento su come trovare quello giusto. Una creazione che include una chiave di idempotenza si può ripetere in sicurezza, come ha mostrato la sessione.

Un limite risponde con 429 e Retry-After, e il CLI esce con codice 7. Questi sono quelli che contano per uno script:

Il riferimento del CLI elenca ogni limite accanto al comando che protegge, e i limiti dei piani sono in Prezzi.

• Flusso di eventi. Il CLI e uno stream REST riproducibile consegnano entrambi gli eventi. Uno schermo offline per 60 secondi ne genera uno, e lo stesso vale per il suo ritorno. Una riconnessione riparte dall’ultimo cursore, gratis. Il digital signage headless registra una pipeline che legge lo stream.
• Notifiche. Un’organizzazione può averne fino a 50 nei suoi progetti. Un’email o un webhook firmato scatta quando uno schermo va offline, perde il display, si surriscalda, non riesce a memorizzare i contenuti, si blocca durante un aggiornamento dei contenuti, mostra un errore invece di riprodurre o continua a bloccarsi. Una condizione scatta dopo che è durata 10 minuti per impostazione predefinita, così una riconnessione rapida resta silenziosa, e crashing scatta subito. Un webhook è un endpoint HTTPS che gestisci tu, e può anche ricevere eventi grezzi del progetto. Ogni consegna è firmata, quindi rifiuta un timestamp vecchio, confronta in tempo costante e deduplica in base all’ID della consegna o dell’evento, perché la consegna è almeno una volta e non ordinata. Rispondi entro 10 secondi. Un tentativo non riuscito viene ripetuto con backoff per 24 ore, e una notifica che fallisce per 72 ore di fila viene disattivata.

Come verifico un webhook?

Ogni consegna include ScreenRig-Signature: t=<unix seconds>,v1=<hex>, dove v1 è un HMAC-SHA256 su <t>.<raw body> con chiave il segreto della notifica, e ScreenRig-Event-Id, che resta uguale tra i tentativi. Calcolalo sui byte grezzi prima di analizzare il JSON:

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body bytes (Buffer) exactly as received.
function verify(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
  if (typeof signatureHeader !== "string" || !signatureHeader) return false;
  const parts = Object.fromEntries(signatureHeader.split(",").map((part) => part.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Quanto velocemente una scrittura arriva allo schermo?

Nell’esecuzione registrata della pipeline, uno script ha scritto una riga del tabellone e lo stream di eventi ha riportato l’intero percorso: la scrittura, la modifica e poi la segnalazione del Player stesso di aver applicato quella revisione a quella pagina (orari in UTC, ridotti a evento e revisione).

03:43:47.501  kv.updated                 revision 5 written
03:43:47.505  screen.card_data_changed   revision 5
03:43:49.306  screen.card_data_applied   revision 5, page "board"

Sono 1.8 secondi da una scrittura accettata al Player che la mostra. Un job che non deve proseguire finché lo schermo non mostra un errore può attendere l’ultima riga. Il digital signage headless riporta l’intera esecuzione.

• Sottoscrizioni MCP. Il server remoto può iscrivere un assistente agli eventi, così può dirti che uno schermo è andato offline. Il riferimento del server MCP contiene i dettagli.

Dodici Player eseguono le playlist di screenRIG: il Player web, Android e Google TV, l’Amazon Signage Stick, Apple TV, macOS, iPhone e iPad, Windows, Linux, Raspberry Pi, LG webOS Signage, Samsung Smart Signage (Tizen) e BrightSign. Ogni Player mostra un codice di associazione, e una chiamata lo riscatta. Apple TV riproduce immagini, video, stream e schede. Le pagine web e le tue app richiedono un altro Player. Player contiene la tabella completa del supporto.

screenRIG ha un’API di digital signage?

Sì. Un’API REST copre schermi, playlist, contenuti multimediali, programmazioni, app, webhook e altro, e un unico file OpenAPI descrive ogni operazione: versione 0.3.0, un file da 3 MB con 736 operazioni su 562 percorsi e 1,059 schemi. Il plugin, i Player e la dashboard usano le stesse operazioni HTTP. Il riferimento API le elenca, e il contratto OpenAPI è un unico file.

screenRIG è un software di digital signage API-first?

Sì. API-first significa che l’API viene per prima e ogni client la usa, e qui la dashboard, il CLI, gli agenti e i Player lo fanno tutti. Il digital signage headless mostra una pipeline che gestisce uno schermo senza alcuna dashboard aperta.

Come invio i miei dati a uno schermo?

Scrivili nei dati di una scheda o nell’archivio chiave/valore di un’app. Un webhook chiave/valore è un URL che scrive una chiave, quindi un punto vendita, uno script di un foglio di calcolo o un cron job può inviare dati agli schermi con un solo HTTP POST. Un’app che si iscrive si aggiorna nel giro di pochi secondi su ogni schermo che la esegue.

Come faccio a sapere quando uno schermo va offline?

Crea una notifica che invia un’email o un webhook firmato, oppure leggi lo stream di eventi riproducibile. Uno schermo è considerato offline dopo 60 secondi, e per impostazione predefinita una notifica attende 10 minuti prima di scattare, così una riconnessione rapida resta silenziosa.

Cosa succede quando raggiungo un limite di frequenza?

L’API risponde 429, e la sua intestazione Retry-After dice quanto attendere. Il CLI esce con codice 7 e mostra retry_after_seconds.

L’API cambierà sotto il mio script?

Le modifiche all’interno di una versione principale sono compatibili: nuovi endpoint, membri di richiesta facoltativi e nuovi codici di problema. Una modifica che rompe una chiamata funzionante richiede una nuova versione principale, che si sovrappone alla precedente per almeno 180 giorni.

L’API di digital signage è gratuita?

screenRIG è gratuito, con schermi illimitati. I piani a pagamento aggiungono strumenti aziendali, più persone, persone con cui parlare, governance e condizioni contrattuali. Le chiamate dal tuo codice contano come richieste dell’agente, e ogni piano ne include un certo numero ogni mese. Vedi i prezzi.

Apri il riferimento API REST, che elenca ogni chiamata vista qui, oppure inizia gratis e lascia che sia il tuo agente a farle. Agenti spiega come un agente si registra da solo.