Iniciar sesión

WebSocket en tiempo real

Controla una sala de Cliqer desde tu propio software como un control remoto, con diapositivas, el temporizador, un puntero láser y mensajes al anfitrión

Conéctate a wss://cliqer.io/ws para controlar una sala de Cliqer desde tu propio software o sistema de control de espectáculos, como si fuera un control remoto. Puedes cambiar diapositivas, manejar el temporizador del anfitrión, señalar con un punto láser y enviar mensajes al anfitrión. Tu aplicación se une a la sala como presentador; la sala siempre la aloja la aplicación de escritorio de Cliqer.

Autenticación: conéctate con un token de sesión: la cookie session_token (los navegadores la envían automáticamente), un parámetro de consulta ?token= o un encabezado Authorization: Bearer. El token se comprueba al conectarte, no en cada comando, así que cuando caduque abre una conexión nueva con un token nuevo y vuelve a unirte. Sin token puedes conectarte, pero no puedes usar la API. Las claves de API de equipo (cliqer_...) solo autentican los endpoints REST; en este socket una clave no es un token de sesión.

Conexión

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

El servidor envía connected con tu clientId en cuanto ha configurado la conexión. Espera a recibirlo antes de enviar nada: si un mensaje llega antes, se rechaza con un error y se cierra la conexión.


Flujo de conexión y sala

Controla las diapositivas de una sala desde tu propio software, como si fuera un control remoto. Tu aplicación se une a la sala como presentador, así que el anfitrión la ve en la lista de presentadores con su presenterName y la gestiona como a cualquier otro presentador: el operador puede desactivar sus clics, expulsarla o bloquearla.

  • Conéctate con un token de sesión (?token=, un encabezado Authorization: Bearer o la cookie session_token). Las claves de API de equipo solo funcionan en los endpoints REST, no en este socket.
  • El plan del propietario de la sala debe incluir la API de cliente: el complemento API en Presenter, Studio HD y Studio 4K, ya incluido en Studio 8K y Enterprise.
  • Los comandos de diapositivas y del temporizador solo se ejecutan mientras el anfitrión permita los clics de tu conexión.

Unirse a la sala

{ "type": "joinRoom", "payload": { "room": "ABC123", "presenterName": "Show control", "api": true } }
  • Envíalo después del evento connected: el servidor rechaza todo lo que llegue antes.
  • presenterName es el nombre que ve el anfitrión (por defecto, API). Tu aplicación siempre es un presentador en la sala, nunca su anfitrión.
  • Espera a recibir un evento clicksEnabled con payload true antes de enviar comandos. El anfitrión lo envía en cuanto ha configurado tu conexión, y de nuevo cada vez que el operador activa o desactiva tus clics.
  • Guarda la presenterKey de joinedRoom y envíala en joinRoom cuando vuelvas a conectarte, para que el anfitrión mantenga tu permiso de clics.
  • Envía la trama de texto ping cada 15 segundos para mantener la conexión abierta. El servidor responde con la trama de texto pong (no JSON).

Enviar comandos

{ "type": "webAction", "payload": { "action": "goto", "slide": 5, "id": "a3" } }
actionCampo adicionalQué hace
nextDiapositiva siguiente (o animación)
prevDiapositiva anterior (o animación)
firstPrimera diapositiva
lastÚltima diapositiva
gotoslide: número entero de 1 a 9999Va a esa diapositiva
blackouton: true o falsePone la pantalla en negro o vuelve a mostrarla
  • id es opcional: de 1 a 64 letras, dígitos, _, ., : o -. Se devuelve en el resultado. Usa un id nuevo para cada comando: el anfitrión descarta cualquier comando cuyo id ya haya recibido de tu conexión en los últimos 5 segundos, así que un reintento del mismo comando se ejecuta una sola vez.
  • first, last, goto y blackout solo se ejecutan en un anfitrión cuyo evento controls más reciente los incluya en nav. Un anfitrión que no envía ningún evento controls solo admite next y prev. Si hay varios anfitriones en la sala, cada uno ejecuta los comandos que admite.
  • next o prev con la pantalla en negro la vuelve a mostrar sin cambiar de diapositiva.
  • Un goto más allá de la última diapositiva se ignora.
  • Envía como máximo 10 comandos por segundo, sumando los de diapositivas y los del temporizador. El anfitrión también descarta la repetición del mismo comando en menos de 50 milisegundos.

Esto es lo que admite actualmente cada aplicación de presentaciones:

Aplicación de presentacionesnext, prevfirst, lastgotoblackout
PowerPoint en WindowsSíSíSíSí
PowerPoint en MacSíSí
No
No
KeynoteSí
No
No
Sí
Google Slides (con la extensión del navegador conectada)SíSí
No
No
vMixSí
No
No
No
Ventana activaSí
No
No
No

El evento controls da la información en directo del anfitrión que estás controlando: consulta nav en ese evento en lugar de fiarte de esta tabla.

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

Resultados y eventos

Cada comando recibe como respuesta un webActionResult o un error.

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

hosts es el número de anfitriones a los que se entregó el comando. La prueba de que se ejecutó es el siguiente evento slide del anfitrión; blackout también cambia blackout en el siguiente evento controls del anfitrión. Un comando que el anfitrión no ejecuta (porque los clics están desactivados, porque no admite ese comando o porque es un goto más allá de la última diapositiva) recibe un resultado, pero ningún evento slide.

errorCuándo
auth_requiredjoinRoom con api: true en una conexión sin token de sesión
not_api_clientUn comando desde una conexión que no se ha unido a una sala con api: true, o que ya la ha abandonado
invalid_web_actionaction desconocida, o un slide, on o id que falta o no es válido
invalid_timer_actionaction de temporizador desconocida, o un minutes o id que falta o no es válido
invalid_messageUn mensaje sin text o de más de 1000 caracteres
invalid_presenter_mouseUna posición del puntero fuera del rango de 0 a 1
rate_limitedMás de 10 comandos de diapositivas y del temporizador en un segundo, o más de 5 mensajes en 10 segundos
no_hostNo hay ningún anfitrión conectado a la sala
host_update_requiredTodos los anfitriones de la sala usan una versión antigua de Cliqer que no acepta comandos de la API
api_not_in_planEl plan del propietario de la sala no incluye la API de cliente

Los errores incluyen un message legible y, si el comando estaba bien formado, su action y su 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" } }

Los eventos de un anfitrión llevan el id de ese anfitrión en hostId:

EventoPayload
clicksEnabledtrue cuando el anfitrión acepta tus comandos, false cuando el operador ha desactivado tus clics
controls{ app, nav, blackout, timer }: la aplicación de presentaciones, los comandos de diapositiva adicionales que admite (first, last, goto, blackout), si la pantalla está en negro y si el anfitrión acepta comandos del temporizador
slide{ number, current, total, title, notes } después de cada comando que ha ejecutado el anfitrión (number es "4/12"; total es null cuando la aplicación no lo indica), o null cuando el anfitrión no tiene ninguna presentación abierta
countdownEl tiempo que muestra el temporizador del anfitrión, como "4:59" ("-0:12" en tiempo extra), cada segundo mientras está en marcha, o null cuando se detiene
countdownPhase{ phase, blink }: phase es idle, talk, warning (queda menos de un minuto), overtime o paused, y blink indica si el temporizador del anfitrión está parpadeando
messageFromHostUna respuesta del operador del anfitrión; consulta Mensajes al anfitrión

También recibes los eventos propios de la sala (clientJoined, clientLeft y otros); ignora los que no uses. Si el operador expulsa o bloquea tu conexión, recibes logout con reason: "kicked".

Temporizador

Maneja el temporizador de la aplicación Cliqer del anfitrión con los mismos comandos que envía un Stream Deck o Bitfocus Companion.

{ "type": "timerAction", "payload": { "action": "set", "minutes": 25, "id": "t1" } }
actionQué hace
startInicia el temporizador o lo reanuda después de stop
stopPausa el temporizador
resetDetiene el temporizador y vuelve al tiempo configurado
plus1, plus2, plus5Añade 1, 2 o 5 minutos
minus1, minus2, minus5Resta 1, 2 o 5 minutos
preset5, preset10, preset15, preset20Detiene el temporizador y lo fija en 5, 10, 15 o 20 minutos
setDetiene el temporizador y lo fija en minutes, un número entero de 1 a 999
  • Cada comando recibe como respuesta un timerActionResult ({ action, id, hosts }, con hosts igual que en las diapositivas) o un error. La prueba de que se ejecutó es el siguiente evento countdown o countdownPhase del anfitrión.
  • El temporizador solo funciona en un anfitrión cuyo evento controls más reciente tenga timer: true. Los anfitriones con una versión antigua de Cliqer no lo anuncian e ignoran los comandos del temporizador.
  • Los comandos del temporizador siguen las mismas reglas que los de diapositivas: el anfitrión solo los ejecuta mientras permita los clics de tu conexión, y comparten el límite de 10 comandos por segundo.
  • La configuración del temporizador del anfitrión se aplica tal cual: un temporizador configurado en modo ascendente cuenta hacia arriba, y un temporizador que sigue a un temporizador de hardware conectado toma el tiempo de ese dispositivo.

Puntero láser

Muestra un punto láser en la pantalla compartida del anfitrión, igual que lo hace el teléfono de un presentador.

{ "type": "presenterMouse", "payload": { "mouse": { "x": 0.5, "y": 0.25 } } }
  • x e y indican la posición en la pantalla compartida desde su esquina superior izquierda, de 0 a 1.
  • Envía { "pressed": false } como payload para ocultar el punto. Si no, desaparece entre 30 y 90 segundos después de tu última posición.
  • El punto solo se muestra mientras el anfitrión comparte una pantalla y tiene activado Puntero láser. Su color depende de tu presenterName.
  • Envía como máximo 30 posiciones por segundo. Las posiciones que sobran se descartan sin error, y no hay ningún evento de resultado.

Mensajes al anfitrión

Envía un mensaje al operador del anfitrión. Aparece en el chat de presentadores del anfitrión igual que un mensaje enviado desde el teléfono de un presentador, y las respuestas del operador llegan como 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"

Respuesta del anfitrión:

{
  "type": "messageFromHost",
  "payload": {
    "fromClientId": "host_abc123",
    "fromPresenterName": "Stage PC",
    "originalPayload": { "text": "Thanks, got it" }
  },
  "hostId": "host_abc123"
}
  • text tiene de 1 a 1000 caracteres. Envía como máximo 5 mensajes cada 10 segundos.
  • Cada mensaje recibe como respuesta un messageToHostsResult ({ id, hosts }) o un error.
  • El operador ve el mensaje con tu presenterName, y el anfitrión muestra una notificación si tiene activado el ajuste Notificaciones.

Referencia de eventos

Eventos salientes (Cliente → Servidor)

EventoDescripción
joinRoomSe une a una sala como cliente de API con api: true (consulta Navegación de diapositivas)
webActionControl de diapositivas (consulta Navegación de diapositivas)
timerActionControl del temporizador (consulta Temporizador)
presenterMousePosición del puntero láser (consulta Puntero láser)
messageToHostsEnvía un mensaje al operador del anfitrión (consulta Mensajes al anfitrión)
logoutSale de la sala; la conexión sigue abierta y puede volver a unirse

Eventos entrantes (Servidor → Cliente)

EventoDescripción
connectedSe envía al abrirse la conexión con { clientId, userId, isAuthenticated }
joinedRoomTe has unido a la sala correctamente
clientJoinedAlguien se ha unido a la sala
clientLeftAlguien ha salido de la sala
webActionResultSe ha entregado un webAction a los anfitriones de la sala
timerActionResultSe ha entregado un timerAction a los anfitriones de la sala
messageToHostsResultSe ha entregado un messageToHosts a los anfitriones de la sala
clicksEnabledIndica si un anfitrión acepta tus comandos
controlsQué admiten la aplicación de presentaciones y el temporizador de un anfitrión
slideLa diapositiva actual de un anfitrión después de un comando
countdownEl tiempo del temporizador de un anfitrión
countdownPhaseLa fase del temporizador de un anfitrión
messageFromHostUn mensaje del operador del anfitrión
logoutEl operador ha expulsado o bloqueado tu conexión (reason: "kicked")
errorMensaje de error