Accedi

WebSocket in tempo reale

Controlla una stanza Cliqer dal tuo software come un telecomando per presentazioni, con slide, timer, puntatore laser e messaggi all'host

Connettiti a wss://cliqer.io/ws per controllare una stanza Cliqer dal tuo software o dal tuo sistema di show control, come un telecomando per presentazioni: cambia slide, gestisci il timer dell'host, punta con un puntino laser e invia messaggi all'host. La tua app entra nella stanza come relatore; la stanza è sempre ospitata dall'app desktop Cliqer.

Autenticazione: connettiti con un token di sessione: il cookie session_token (i browser lo inviano automaticamente), un parametro di query ?token= o un header Authorization: Bearer. Il token viene verificato al momento della connessione, non a ogni comando, quindi quando scade apri una nuova connessione con un token nuovo ed entra di nuovo nella stanza. Senza token puoi connetterti, ma non puoi usare l'API. Le chiavi API del team (cliqer_...) autenticano solo gli endpoint REST; su questo socket una chiave non è un token di sessione.

Connessione

# WebSocket connections require a WebSocket client
# Using websocat for testing:
websocat "$WS_URL/ws?token=YOUR_ACCESS_TOKEN"

Il server invia connected con il tuo clientId una volta configurata la connessione. Attendilo prima di inviare qualsiasi cosa: un messaggio che arriva prima viene rifiutato con un error e la connessione viene chiusa.


Flusso di connessione e stanza

Controlla le slide di una stanza dal tuo software, come un telecomando per presentazioni. La tua app entra nella stanza come relatore, quindi l'host la vede nell'elenco dei relatori con il suo presenterName e la gestisce come qualsiasi altro relatore: l'operatore può disattivarne i clic, rimuoverla o bloccarla.

  • Connettiti con un token di sessione (?token=, un header Authorization: Bearer o il cookie session_token). Le chiavi API del team funzionano solo sugli endpoint REST, non su questo socket.
  • Il piano del proprietario della stanza deve includere la Client API: l'add-on API su Presenter, Studio HD e Studio 4K, inclusa in Studio 8K ed Enterprise.
  • I comandi per slide e timer vengono eseguiti solo mentre l'host consente i clic dalla tua connessione.

Entra nella stanza

{ "type": "joinRoom", "payload": { "room": "ABC123", "presenterName": "Show control", "api": true } }
  • Invialo dopo l'evento connected: il server rifiuta qualsiasi cosa arrivi prima.
  • presenterName è il nome che vede l'host (predefinito API). La tua app è sempre un relatore nella stanza, mai il suo host.
  • Attendi un evento clicksEnabled con payload true prima di inviare comandi. L'host lo invia una volta configurata la tua connessione, e di nuovo ogni volta che l'operatore attiva o disattiva i tuoi clic.
  • Conserva la presenterKey ricevuta in joinedRoom e inviala in joinRoom quando ti riconnetti, così l'host mantiene il tuo permesso di clic.
  • Invia il frame di testo ping ogni 15 secondi per mantenere aperta la connessione. Il server risponde con il frame di testo pong (non JSON).

Invia i comandi

{ "type": "webAction", "payload": { "action": "goto", "slide": 5, "id": "a3" } }
actionCampo aggiuntivoCosa fa
nextSlide successiva (o animazione successiva)
prevSlide precedente (o animazione precedente)
firstPrima slide
lastUltima slide
gotoslide: numero intero da 1 a 9999Vai a quella slide
blackouton: true o falseOscura lo schermo o mostralo di nuovo
  • id è facoltativo: da 1 a 64 lettere, cifre, _, ., : o -. Viene restituito nel risultato. Usa un nuovo id per ogni comando: l'host scarta un comando il cui id ha già ricevuto dalla tua connessione negli ultimi 5 secondi, quindi un nuovo tentativo dello stesso comando viene eseguito una sola volta.
  • first, last, goto e blackout vengono eseguiti solo su un host il cui evento controls più recente li elenca in nav. Un host che non invia alcun evento controls supporta solo next e prev. Con più host nella stanza, ogni host esegue i comandi che supporta.
  • next o prev con lo schermo oscurato lo mostrano di nuovo senza cambiare slide.
  • Un goto oltre l'ultima slide viene ignorato.
  • Invia al massimo 10 comandi al secondo, contando insieme i comandi per slide e timer. L'host scarta anche una ripetizione dello stesso comando entro 50 millisecondi.

Cosa supporta oggi ogni app di presentazione:

App di presentazionenext, prevfirst, lastgotoblackout
PowerPoint su WindowsSìSìSìSì
PowerPoint su MacSìSì
No
No
KeynoteSì
No
No
Sì
Google Slides (estensione del browser connessa)SìSì
No
No
vMixSì
No
No
No
Finestra in primo pianoSì
No
No
No

L'evento controls è la risposta in tempo reale per l'host che stai controllando: leggi nav da lì anziché da questa tabella.

# One connection: wait for `connected`, join as an API client, give the host a
# moment to set it up, then send commands. Replies print as they arrive.
( sleep 2
  echo '{"type":"joinRoom","payload":{"room":"ABC123","presenterName":"Show control","api":true}}'
  sleep 3
  echo '{"type":"webAction","payload":{"action":"next","id":"a1"}}'
  sleep 1
  echo '{"type":"webAction","payload":{"action":"prev","id":"a2"}}'
  sleep 1 ) | websocat "$WS_URL/ws?token=YOUR_SESSION_TOKEN"

Risultati ed eventi

Ogni comando riceve in risposta un webActionResult o un error.

{ "type": "webActionResult", "payload": { "action": "next", "id": "a1", "hosts": 1 } }

hosts è il numero di host a cui il comando è stato consegnato. La prova che è stato eseguito è il successivo evento slide dell'host; blackout modifica anche blackout nel successivo evento controls dell'host. Un comando che l'host non esegue (clic disattivati, un comando che non supporta, un goto oltre l'ultima slide) riceve un risultato ma nessun evento slide.

errorQuando
auth_requiredjoinRoom con api: true su una connessione senza token di sessione
not_api_clientUn comando da una connessione che non è entrata in una stanza con api: true, o dopo che l'ha lasciata
invalid_web_actionaction sconosciuta, oppure slide, on o id mancante o non valido
invalid_timer_actionaction del timer sconosciuta, oppure minutes o id mancante o non valido
invalid_messageUn messaggio senza text o più lungo di 1000 caratteri
invalid_presenter_mouseUna posizione del puntatore fuori dall'intervallo da 0 a 1
rate_limitedPiù di 10 comandi per slide e timer in un secondo, o più di 5 messaggi in 10 secondi
no_hostNessun host è connesso alla stanza
host_update_requiredTutti gli host nella stanza usano una versione di Cliqer meno recente che non accetta comandi dall'API
api_not_in_planIl piano del proprietario della stanza non include la Client API

Gli errori contengono un message leggibile e, quando il comando era ben formato, la sua action e il suo id:

{ "type": "error", "error": "invalid_web_action", "payload": { "message": "Unknown or incomplete webAction. Use next, prev, first, last, goto with slide, or blackout with on.", "action": "goto", "id": "a3" } }

Gli eventi di un host riportano l'id di quell'host in hostId:

EventoPayload
clicksEnabledtrue quando l'host accetta i tuoi comandi, false quando l'operatore ha disattivato i tuoi clic
controls{ app, nav, blackout, timer }: l'app di presentazione, i comandi aggiuntivi per le slide che supporta (first, last, goto, blackout), se lo schermo è oscurato e se l'host accetta comandi per il timer
slide{ number, current, total, title, notes } dopo ogni comando eseguito dall'host (number è "4/12", total è null quando l'app non lo comunica), oppure null quando l'host non ha alcuna presentazione aperta
countdownIl tempo mostrato dal timer dell'host, ad esempio "4:59" ("-0:12" a tempo scaduto), ogni secondo mentre è in funzione, oppure null quando si ferma
countdownPhase{ phase, blink }: phase è idle, talk, warning (meno di un minuto rimanente), overtime o paused, e blink indica se il timer dell'host sta lampeggiando
messageFromHostUna risposta dell'operatore dell'host, vedi Messaggi all'host

Ricevi anche gli eventi propri della stanza (clientJoined, clientLeft e altri); ignora quelli che non usi. Se l'operatore rimuove o blocca la tua connessione, ricevi logout con reason: "kicked".

Timer

Gestisci il timer nell'app Cliqer dell'host con gli stessi comandi che invia uno Stream Deck o Bitfocus Companion.

{ "type": "timerAction", "payload": { "action": "set", "minutes": 25, "id": "t1" } }
actionCosa fa
startAvvia il timer o riprendilo dopo stop
stopMetti in pausa il timer
resetFerma il timer e torna al tempo impostato
plus1, plus2, plus5Aggiungi 1, 2 o 5 minuti
minus1, minus2, minus5Togli 1, 2 o 5 minuti
preset5, preset10, preset15, preset20Ferma il timer e imposta 5, 10, 15 o 20 minuti
setFerma il timer e imposta minutes, un numero intero da 1 a 999
  • Ogni comando riceve in risposta un timerActionResult ({ action, id, hosts }, con hosts come per le slide) o un error. La prova che è stato eseguito è il successivo evento countdown o countdownPhase dell'host.
  • Il timer funziona solo su un host il cui evento controls più recente contiene timer: true. Gli host con una versione di Cliqer meno recente non lo annunciano e ignorano i comandi per il timer.
  • I comandi per il timer seguono le stesse regole dei comandi per le slide: l'host li esegue solo mentre consente i clic dalla tua connessione, e condividono il limite di 10 comandi al secondo.
  • Le impostazioni del timer dell'host si applicano così come sono: un timer impostato per contare in avanti conta in avanti, e un timer che segue un timer hardware connesso prende il tempo da quel dispositivo.

Puntatore laser

Mostra un puntino laser sullo schermo condiviso dell'host, come fa il telefono di un relatore.

{ "type": "presenterMouse", "payload": { "mouse": { "x": 0.5, "y": 0.25 } } }
  • x e y sono la posizione sullo schermo condiviso a partire dall'angolo in alto a sinistra, da 0 a 1.
  • Invia { "pressed": false } come payload per nascondere il puntino. Altrimenti scompare da 30 a 90 secondi dopo la tua ultima posizione.
  • Il puntino compare solo mentre l'host condivide uno schermo e ha Puntatore laser attivo. Il suo colore dipende dal tuo presenterName.
  • Invia al massimo 30 posizioni al secondo. Le posizioni in eccesso vengono scartate senza errore e non c'è alcun evento di risultato.

Messaggi all'host

Invia un messaggio all'operatore dell'host. Compare nella chat dei relatori dell'host, come un messaggio inviato dal telefono di un relatore, e le risposte dell'operatore tornano come messageFromHost.

# Join as an API client, then send a message. Replies print as they arrive.
( sleep 2
  echo '{"type":"joinRoom","payload":{"room":"ABC123","presenterName":"Show control","api":true}}'
  sleep 3
  echo '{"type":"messageToHosts","payload":{"text":"Two minutes to the break","id":"m1"}}'
  sleep 30 ) | websocat "$WS_URL/ws?token=YOUR_SESSION_TOKEN"

Risposta dell'host:

{
  "type": "messageFromHost",
  "payload": {
    "fromClientId": "host_abc123",
    "fromPresenterName": "Stage PC",
    "originalPayload": { "text": "Thanks, got it" }
  },
  "hostId": "host_abc123"
}
  • text è lungo da 1 a 1000 caratteri. Invia al massimo 5 messaggi ogni 10 secondi.
  • Ogni messaggio riceve in risposta un messageToHostsResult ({ id, hosts }) o un error.
  • L'operatore vede il messaggio con il tuo presenterName e l'host mostra una notifica quando l'impostazione Notifiche è attiva.

Riferimento degli eventi

Eventi in uscita (Client → Server)

EventoDescrizione
joinRoomEntra in una stanza come client API con api: true (vedi Navigazione delle slide)
webActionControllo delle slide (vedi Navigazione delle slide)
timerActionControllo del timer (vedi Timer)
presenterMousePosizione del puntatore laser (vedi Puntatore laser)
messageToHostsInvia un messaggio all'operatore dell'host (vedi Messaggi all'host)
logoutLascia la stanza; la connessione resta aperta e può entrare di nuovo

Eventi in entrata (Server → Client)

EventoDescrizione
connectedInviato all'apertura con { clientId, userId, isAuthenticated }
joinedRoomIngresso nella stanza riuscito
clientJoinedQualcuno è entrato nella stanza
clientLeftQualcuno ha lasciato la stanza
webActionResultUna webAction è stata consegnata agli host della stanza
timerActionResultUna timerAction è stata consegnata agli host della stanza
messageToHostsResultUn messageToHosts è stato consegnato agli host della stanza
clicksEnabledSe un host accetta i tuoi comandi
controlsCosa supportano l'app di presentazione e il timer di un host
slideLa slide corrente di un host dopo un comando
countdownIl tempo sul timer di un host
countdownPhaseLa fase del timer di un host
messageFromHostUn messaggio dall'operatore dell'host
logoutL'operatore ha rimosso o bloccato la tua connessione (reason: "kicked")
errorMessaggio di errore