Se connecter

WebSocket en temps réel

Pilotez une salle Cliqer depuis votre propre logiciel comme avec une télécommande de présentation : diapositives, minuteur, pointeur laser et messages à l'hôte

Connectez-vous à wss://cliqer.io/ws pour piloter une salle Cliqer depuis votre propre logiciel ou votre système de show control, comme avec une télécommande de présentation : changez de diapositive, pilotez le minuteur de l'hôte, pointez avec un point laser et envoyez des messages à l'hôte. Votre application rejoint la salle en tant que présentateur ; la salle elle-même est toujours hébergée par l'application de bureau Cliqer.

Authentification : connectez-vous avec un jeton de session, c'est-à-dire le cookie session_token (les navigateurs l'envoient automatiquement), un paramètre de requête ?token= ou un en-tête Authorization: Bearer. Le jeton est vérifié à la connexion, et non à chaque commande : lorsqu'il expire, ouvrez une nouvelle connexion avec un nouveau jeton et rejoignez à nouveau la salle. Sans jeton, vous pouvez vous connecter mais pas utiliser l'API. Les clés API d'équipe (cliqer_...) authentifient uniquement les points de terminaison REST ; sur ce socket, une clé n'est pas un jeton de session.

Connexion

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

Le serveur envoie connected avec votre clientId dès qu'il a établi la connexion. Attendez cet événement avant d'envoyer quoi que ce soit : un message qui arrive plus tôt est rejeté avec une error et la connexion est fermée.


Connexion et déroulement dans la salle

Pilotez les diapositives d'une salle depuis votre propre logiciel, comme avec une télécommande de présentation. Votre application rejoint la salle en tant que présentateur, si bien que l'hôte la voit dans la liste des présentateurs sous son presenterName et la gère comme tout autre présentateur : l'opérateur peut désactiver ses clics, la retirer ou la bloquer.

  • Connectez-vous avec un jeton de session (?token=, un en-tête Authorization: Bearer ou le cookie session_token). Les clés API d'équipe fonctionnent uniquement sur les points de terminaison REST, pas sur ce socket.
  • Le forfait du propriétaire de la salle doit inclure l'API client : le module complémentaire API sur Presenter, Studio HD et Studio 4K, inclus dans Studio 8K et Enterprise.
  • Les commandes de diapositives et de minuteur ne s'exécutent que tant que l'hôte autorise les clics de votre connexion.

Rejoindre la salle

{ "type": "joinRoom", "payload": { "room": "ABC123", "presenterName": "Show control", "api": true } }
  • Envoyez ce message après l'événement connected : le serveur rejette tout ce qui arrive avant.
  • presenterName est le nom que voit l'hôte (par défaut API). Votre application est toujours un présentateur dans la salle, jamais son hôte.
  • Attendez un événement clicksEnabled avec la charge utile true avant d'envoyer des commandes. L'hôte l'envoie dès qu'il a configuré votre connexion, puis chaque fois que l'opérateur active ou désactive vos clics.
  • Conservez la presenterKey reçue dans joinedRoom et renvoyez-la dans joinRoom lorsque vous vous reconnectez, afin que l'hôte conserve votre autorisation de clic.
  • Envoyez la trame texte ping toutes les 15 secondes pour maintenir la connexion ouverte. Le serveur répond par la trame texte pong (pas du JSON).

Envoyer des commandes

{ "type": "webAction", "payload": { "action": "goto", "slide": 5, "id": "a3" } }
actionChamp supplémentaireEffet
nextDiapositive (ou animation) suivante
prevDiapositive (ou animation) précédente
firstPremière diapositive
lastDernière diapositive
gotoslide : nombre entier de 1 à 9999Aller à cette diapositive
blackouton : true ou falsePasser l'écran au noir, ou le réafficher
  • id est facultatif : de 1 à 64 lettres, chiffres, _, ., : ou -. Il est renvoyé dans le résultat. Utilisez un nouvel id pour chaque commande : l'hôte ignore une commande dont il a déjà reçu l'id de votre connexion au cours des 5 dernières secondes, de sorte qu'une nouvelle tentative de la même commande ne s'exécute qu'une seule fois.
  • first, last, goto et blackout ne s'exécutent que sur un hôte dont le dernier événement controls les liste dans nav. Un hôte qui n'envoie aucun événement controls prend uniquement en charge next et prev. Lorsque la salle compte plusieurs hôtes, chacun exécute les commandes qu'il prend en charge.
  • next ou prev pendant que l'écran est au noir le réaffiche sans changer de diapositive.
  • Un goto au-delà de la dernière diapositive est ignoré.
  • Envoyez au maximum 10 commandes par seconde, commandes de diapositives et de minuteur confondues. L'hôte ignore également toute répétition d'une même commande dans un délai de 50 millisecondes.

Ce que chaque application de présentation prend en charge aujourd'hui :

Application de présentationnext, prevfirst, lastgotoblackout
PowerPoint sur WindowsOuiOuiOuiOui
PowerPoint sur MacOuiOuiNonNon
KeynoteOuiNonNonOui
Google Slides (extension de navigateur connectée)OuiOuiNonNon
vMixOuiNonNonNon
Fenêtre activeOuiNonNonNon

L'événement controls donne la réponse en direct pour l'hôte que vous pilotez : lisez nav dans cet événement plutôt que dans ce tableau.

# 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"

Résultats et événements

Chaque commande reçoit en réponse un webActionResult ou une error.

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

hosts est le nombre d'hôtes auxquels la commande a été remise. La preuve de son exécution est le prochain événement slide de l'hôte ; blackout modifie aussi blackout dans le prochain événement controls de l'hôte. Une commande que l'hôte n'exécute pas (clics désactivés, commande non prise en charge, goto au-delà de la dernière diapositive) reçoit un résultat mais aucun événement slide.

errorQuand
auth_requiredjoinRoom avec api: true sur une connexion sans jeton de session
not_api_clientUne commande provenant d'une connexion qui n'a pas rejoint de salle avec api: true, ou qui l'a quittée
invalid_web_actionaction inconnue, ou slide, on ou id manquant ou invalide
invalid_timer_actionaction de minuteur inconnue, ou minutes ou id manquant ou invalide
invalid_messageUn message sans text, ou de plus de 1000 caractères
invalid_presenter_mouseUne position du pointeur en dehors de l'intervalle 0 à 1
rate_limitedPlus de 10 commandes de diapositives et de minuteur en une seconde, ou plus de 5 messages en 10 secondes
no_hostAucun hôte n'est connecté à la salle
host_update_requiredTous les hôtes de la salle utilisent une ancienne version de Cliqer qui ne peut pas recevoir de commandes de l'API
api_not_in_planLe forfait du propriétaire de la salle n'inclut pas l'API client

Les erreurs contiennent un message lisible et, lorsque la commande était bien formée, son action et son 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" } }

Les événements provenant d'un hôte portent l'identifiant de cet hôte dans hostId :

ÉvénementCharge utile
clicksEnabledtrue lorsque l'hôte accepte vos commandes, false lorsque l'opérateur a désactivé vos clics
controls{ app, nav, blackout, timer } : l'application de présentation, les commandes de diapositives supplémentaires qu'elle prend en charge (first, last, goto, blackout), si l'écran est au noir, et si l'hôte accepte les commandes de minuteur
slide{ number, current, total, title, notes } après chaque commande exécutée par l'hôte (number vaut "4/12", total vaut null lorsque l'application ne le communique pas), ou null lorsque l'hôte n'a aucune présentation ouverte
countdownLe temps affiché par le minuteur de l'hôte, par exemple "4:59" ("-0:12" en dépassement), chaque seconde pendant qu'il tourne, ou null lorsqu'il s'arrête
countdownPhase{ phase, blink } : phase vaut idle, talk, warning (moins d'une minute restante), overtime ou paused, et blink indique si le minuteur de l'hôte clignote
messageFromHostUne réponse de l'opérateur de l'hôte, voir Messages à l'hôte

Vous recevez aussi les événements propres à la salle (clientJoined, clientLeft et d'autres) ; ignorez ceux dont vous n'avez pas besoin. Si l'opérateur retire ou bloque votre connexion, vous recevez logout avec reason: "kicked".

Minuteur

Pilotez le minuteur de l'application Cliqer de l'hôte avec les mêmes commandes que celles qu'envoie un Stream Deck ou Bitfocus Companion.

{ "type": "timerAction", "payload": { "action": "set", "minutes": 25, "id": "t1" } }
actionEffet
startDémarrer le minuteur, ou le reprendre après stop
stopMettre le minuteur en pause
resetArrêter le minuteur et revenir à la durée réglée
plus1, plus2, plus5Ajouter 1, 2 ou 5 minutes
minus1, minus2, minus5Retirer 1, 2 ou 5 minutes
preset5, preset10, preset15, preset20Arrêter le minuteur et régler 5, 10, 15 ou 20 minutes
setArrêter le minuteur et régler minutes, un nombre entier de 1 à 999
  • Chaque commande reçoit en réponse un timerActionResult ({ action, id, hosts }, hosts comme pour les diapositives) ou une error. La preuve de son exécution est le prochain événement countdown ou countdownPhase de l'hôte.
  • Le minuteur ne fonctionne que sur un hôte dont le dernier événement controls contient timer: true. Les hôtes équipés d'une ancienne version de Cliqer ne l'annoncent pas et ignorent les commandes de minuteur.
  • Les commandes de minuteur suivent les mêmes règles que les commandes de diapositives : l'hôte ne les exécute que tant qu'il autorise les clics de votre connexion, et elles partagent le quota de 10 commandes par seconde.
  • Les réglages du minuteur de l'hôte s'appliquent tels quels : un minuteur réglé en mode progressif compte vers le haut, et un minuteur qui suit un minuteur matériel connecté prend son temps sur cet appareil.

Pointeur laser

Affichez un point laser sur l'écran partagé de l'hôte, comme le fait le téléphone d'un présentateur.

{ "type": "presenterMouse", "payload": { "mouse": { "x": 0.5, "y": 0.25 } } }
  • x et y indiquent la position sur l'écran partagé à partir de son coin supérieur gauche, de 0 à 1.
  • Envoyez { "pressed": false } comme charge utile pour masquer le point. Sinon, il disparaît 30 à 90 secondes après votre dernière position.
  • Le point ne s'affiche que lorsque l'hôte partage un écran et que Pointeur laser est activé. Sa couleur dépend de votre presenterName.
  • Envoyez au maximum 30 positions par seconde. Les positions excédentaires sont ignorées sans erreur, et il n'y a aucun événement de résultat.

Messages à l'hôte

Envoyez un message à l'opérateur de l'hôte. Il apparaît dans le chat des présentateurs de l'hôte, comme un message envoyé depuis le téléphone d'un présentateur, et les réponses de l'opérateur reviennent sous forme de 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"

Réponse de l'hôte :

{
  "type": "messageFromHost",
  "payload": {
    "fromClientId": "host_abc123",
    "fromPresenterName": "Stage PC",
    "originalPayload": { "text": "Thanks, got it" }
  },
  "hostId": "host_abc123"
}
  • text comprend de 1 à 1000 caractères. Envoyez au maximum 5 messages toutes les 10 secondes.
  • Chaque message reçoit en réponse un messageToHostsResult ({ id, hosts }) ou une error.
  • L'opérateur voit le message sous votre presenterName, et l'hôte affiche une notification lorsque son réglage Notifications est activé.

Référence des événements

Événements sortants (client → serveur)

ÉvénementDescription
joinRoomRejoindre une salle en tant que client API avec api: true (voir Navigation dans les diapositives)
webActionContrôle des diapositives (voir Navigation dans les diapositives)
timerActionContrôle du minuteur (voir Minuteur)
presenterMousePosition du pointeur laser (voir Pointeur laser)
messageToHostsEnvoyer un message à l'opérateur de l'hôte (voir Messages à l'hôte)
logoutQuitter la salle ; la connexion reste ouverte et peut rejoindre à nouveau une salle

Événements entrants (serveur → client)

ÉvénementDescription
connectedEnvoyé à l'ouverture avec { clientId, userId, isAuthenticated }
joinedRoomSalle rejointe avec succès
clientJoinedQuelqu'un a rejoint la salle
clientLeftQuelqu'un a quitté la salle
webActionResultUn webAction a été remis aux hôtes de la salle
timerActionResultUn timerAction a été remis aux hôtes de la salle
messageToHostsResultUn messageToHosts a été remis aux hôtes de la salle
clicksEnabledIndique si un hôte accepte vos commandes
controlsCe que prennent en charge l'application de présentation et le minuteur d'un hôte
slideLa diapositive actuelle d'un hôte après une commande
countdownLe temps affiché par le minuteur d'un hôte
countdownPhaseLa phase du minuteur d'un hôte
messageFromHostUn message de l'opérateur de l'hôte
logoutL'opérateur a retiré ou bloqué votre connexion (reason: "kicked")
errorMessage d'erreur