Zaloguj się

WebSocket w czasie rzeczywistym

Steruj pokojem Cliqer z własnego oprogramowania jak pilotem do prezentacji: slajdy, timer, wskaźnik laserowy i wiadomości do hosta

Połącz się z wss://cliqer.io/ws, aby sterować pokojem Cliqer z własnego oprogramowania lub systemu show control jak pilotem do prezentacji: zmieniaj slajdy, steruj timerem hosta, wskazuj kropką lasera i wysyłaj wiadomości do hosta. Twoja aplikacja dołącza do pokoju jako prezenter; hostem pokoju jest zawsze aplikacja desktopowa Cliqer.

Uwierzytelnianie: połącz się, używając tokenu sesji: ciasteczka session_token (przeglądarki wysyłają je automatycznie), parametru zapytania ?token= lub nagłówka Authorization: Bearer. Token jest sprawdzany przy nawiązywaniu połączenia, a nie przy każdym poleceniu, więc gdy wygaśnie, otwórz nowe połączenie ze świeżym tokenem i dołącz ponownie. Bez tokenu możesz się połączyć, ale nie możesz korzystać z API. Klucze API zespołu (cliqer_...) uwierzytelniają wyłącznie endpointy REST; na tym gnieździe klucz nie jest tokenem sesji.

Połączenie

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

Serwer wysyła connected z Twoim clientId, gdy tylko skonfiguruje połączenie. Zaczekaj na to zdarzenie, zanim cokolwiek wyślesz: wiadomość, która dotrze wcześniej, zostaje odrzucona z error, a połączenie zostaje zamknięte.


Połączenie i przebieg pracy w pokoju

Nawigacja po slajdach

Steruj slajdami w pokoju z własnego oprogramowania, jak pilotem do prezentacji. Twoja aplikacja dołącza do pokoju jako prezenter, więc host widzi ją na liście prezenterów pod nazwą presenterName i steruje nią jak każdym innym prezenterem: operator może wyłączyć jej kliknięcia, usunąć ją lub zablokować.

  • Połącz się, używając tokenu sesji (?token=, nagłówka Authorization: Bearer lub ciasteczka session_token). Klucze API zespołu działają tylko na endpointach REST, nie na tym gnieździe.
  • Plan właściciela pokoju musi obejmować Client API: dodatek API w planach Presenter, Studio HD i Studio 4K, w cenie planów Studio 8K i Enterprise.
  • Polecenia slajdów i timera działają tylko wtedy, gdy host zezwala na kliknięcia z Twojego połączenia.

Dołączanie do pokoju

{ "type": "joinRoom", "payload": { "room": "ABC123", "presenterName": "Show control", "api": true } }
  • Wyślij tę wiadomość po zdarzeniu connected: serwer odrzuca wszystko, co dotrze wcześniej.
  • presenterName to nazwa, którą widzi host (domyślnie API). Twoja aplikacja jest w pokoju zawsze prezenterem, nigdy jego hostem.
  • Zanim wyślesz polecenia, zaczekaj na zdarzenie clicksEnabled z payloadem true. Host wysyła je, gdy skonfiguruje Twoje połączenie, i ponownie za każdym razem, gdy operator włączy lub wyłączy Twoje kliknięcia.
  • Zachowaj presenterKey z joinedRoom i wysyłaj go w joinRoom przy ponownym połączeniu, aby host zachował Twoje uprawnienie do klikania.
  • Co 15 sekund wysyłaj ramkę tekstową ping, aby utrzymać połączenie. Serwer odpowiada ramką tekstową pong (nie JSON).

Wysyłanie poleceń

{ "type": "webAction", "payload": { "action": "goto", "slide": 5, "id": "a3" } }
actionDodatkowe poleDziałanie
nextNastępny slajd (lub krok animacji)
prevPoprzedni slajd (lub krok animacji)
firstPierwszy slajd
lastOstatni slajd
gotoslide: liczba całkowita od 1 do 9999Przejście do wskazanego slajdu
blackouton: true lub falseWygaszenie ekranu na czarno lub ponowne jego wyświetlenie
  • id jest opcjonalne: od 1 do 64 liter, cyfr, znaków _, ., : lub -. Wraca w wyniku. Używaj nowego id dla każdego polecenia: host odrzuca polecenie, którego id otrzymał już z Twojego połączenia w ciągu ostatnich 5 sekund, więc ponowienie tego samego polecenia wykona się tylko raz.
  • first, last, goto i blackout działają tylko na hoście, którego najnowsze zdarzenie controls wymienia je w nav. Host, który nie wysyła zdarzenia controls, obsługuje tylko next i prev. Gdy w pokoju jest kilku hostów, każdy z nich wykonuje polecenia, które obsługuje.
  • next lub prev przy wygaszonym ekranie przywraca obraz bez zmiany slajdu.
  • goto poza ostatni slajd jest ignorowane.
  • Wysyłaj maksymalnie 10 poleceń na sekundę, łącznie polecenia slajdów i timera. Host odrzuca też powtórzenie tego samego polecenia w ciągu 50 milisekund.

Co obecnie obsługuje każda aplikacja do prezentacji:

Aplikacja do prezentacjinext, prevfirst, lastgotoblackout
PowerPoint w systemie WindowsTakTakTakTak
PowerPoint na MacTakTakNieNie
KeynoteTakNieNieTak
Google Slides (z podłączonym rozszerzeniem przeglądarki)TakTakNieNie
vMixTakNieNieNie
Aktywne oknoTakNieNieNie

Zdarzenie controls to aktualna informacja o hoście, którym sterujesz: odczytuj nav z niego, a nie z tej tabeli.

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

Wyniki i zdarzenia

Na każde polecenie przychodzi odpowiedź webActionResult lub error.

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

hosts to liczba hostów, do których polecenie zostało dostarczone. Dowodem jego wykonania jest kolejne zdarzenie slide od hosta; blackout zmienia też wartość blackout w kolejnym zdarzeniu controls hosta. Polecenie, którego host nie wykona (kliknięcia wyłączone, nieobsługiwane polecenie, goto poza ostatni slajd), otrzymuje wynik, ale nie wywołuje zdarzenia slide.

errorKiedy
auth_requiredjoinRoom z api: true na połączeniu bez tokenu sesji
not_api_clientPolecenie z połączenia, które nie dołączyło do pokoju z api: true lub już go opuściło
invalid_web_actionNieznana wartość action albo brakujące lub nieprawidłowe slide, on lub id
invalid_timer_actionNieznana wartość action timera albo brakujące lub nieprawidłowe minutes lub id
invalid_messageWiadomość bez text lub dłuższa niż 1000 znaków
invalid_presenter_mousePozycja wskaźnika poza zakresem od 0 do 1
rate_limitedPonad 10 poleceń slajdów i timera w ciągu jednej sekundy lub ponad 5 wiadomości w ciągu 10 sekund
no_hostZ pokojem nie jest połączony żaden host
host_update_requiredKażdy host w pokoju używa starszej wersji Cliqer, która nie przyjmuje poleceń z API
api_not_in_planPlan właściciela pokoju nie obejmuje Client API

Błędy zawierają czytelny komunikat message oraz, jeśli polecenie było poprawnie sformułowane, jego action i 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" } }

Zdarzenia od hosta zawierają jego identyfikator w hostId:

ZdarzeniePayload
clicksEnabledtrue, gdy host przyjmuje Twoje polecenia, false, gdy operator wyłączył Twoje kliknięcia
controls{ app, nav, blackout, timer }: aplikacja do prezentacji, dodatkowe obsługiwane przez nią polecenia slajdów (first, last, goto, blackout), informacja, czy ekran jest wygaszony, oraz czy host przyjmuje polecenia timera
slide{ number, current, total, title, notes } po każdym poleceniu wykonanym przez hosta (number to "4/12", total ma wartość null, gdy aplikacja go nie podaje) lub null, gdy host nie ma otwartej prezentacji
countdownCzas wyświetlany przez timer hosta, np. "4:59" ("-0:12" po przekroczeniu czasu), co sekundę, gdy timer działa, lub null, gdy się zatrzyma
countdownPhase{ phase, blink }: phase to idle, talk, warning (zostało mniej niż minuta), overtime lub paused, a blink określa, czy timer hosta miga
messageFromHostOdpowiedź od operatora hosta, zobacz Wiadomości do hosta

Otrzymujesz też własne zdarzenia pokoju (clientJoined, clientLeft i inne); ignoruj te, których nie używasz. Jeśli operator usunie lub zablokuje Twoje połączenie, otrzymasz logout z reason: "kicked".

Timer

Steruj timerem w aplikacji Cliqer hosta za pomocą tych samych poleceń, które wysyła Stream Deck lub Bitfocus Companion.

{ "type": "timerAction", "payload": { "action": "set", "minutes": 25, "id": "t1" } }
actionDziałanie
startUruchamia timer lub wznawia go po stop
stopWstrzymuje timer
resetZatrzymuje timer i przywraca ustawiony czas
plus1, plus2, plus5Dodaje 1, 2 lub 5 minut
minus1, minus2, minus5Odejmuje 1, 2 lub 5 minut
preset5, preset10, preset15, preset20Zatrzymuje timer i ustawia 5, 10, 15 lub 20 minut
setZatrzymuje timer i ustawia minutes, liczbę całkowitą od 1 do 999
  • Na każde polecenie przychodzi odpowiedź timerActionResult ({ action, id, hosts }, hosts jak w przypadku slajdów) lub error. Dowodem wykonania jest kolejne zdarzenie countdown lub countdownPhase od hosta.
  • Timer działa tylko na hoście, którego najnowsze zdarzenie controls zawiera timer: true. Hosty ze starszą wersją Cliqer tego nie ogłaszają i ignorują polecenia timera.
  • Polecenia timera podlegają tym samym zasadom co polecenia slajdów: host wykonuje je tylko wtedy, gdy zezwala na kliknięcia z Twojego połączenia, a limit 10 poleceń na sekundę jest dla nich wspólny.
  • Ustawienia timera hosta obowiązują bez zmian: timer ustawiony na liczenie w górę liczy w górę, a timer powiązany z podłączonym timerem sprzętowym pobiera czas z tego urządzenia.

Wskaźnik laserowy

Wyświetlaj kropkę lasera na ekranie udostępnianym przez hosta, tak jak robi to telefon prezentera.

{ "type": "presenterMouse", "payload": { "mouse": { "x": 0.5, "y": 0.25 } } }
  • x i y to pozycja na udostępnianym ekranie liczona od jego lewego górnego rogu, od 0 do 1.
  • Wyślij { "pressed": false } jako payload, aby ukryć kropkę. W przeciwnym razie zniknie ona od 30 do 90 sekund po wysłaniu ostatniej pozycji.
  • Kropka jest widoczna tylko wtedy, gdy host udostępnia ekran i ma włączony Wskaźnik laserowy. Jej kolor zależy od Twojego presenterName.
  • Wysyłaj maksymalnie 30 pozycji na sekundę. Nadmiarowe pozycje są odrzucane bez błędu i nie ma zdarzenia wyniku.

Wiadomości do hosta

Wyślij wiadomość do operatora hosta. Pojawi się ona w czacie prezenterów u hosta, tak samo jak wiadomość z telefonu prezentera, a odpowiedzi operatora wracają jako 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"

Odpowiedź od hosta:

{
  "type": "messageFromHost",
  "payload": {
    "fromClientId": "host_abc123",
    "fromPresenterName": "Stage PC",
    "originalPayload": { "text": "Thanks, got it" }
  },
  "hostId": "host_abc123"
}
  • text ma od 1 do 1000 znaków. Wysyłaj maksymalnie 5 wiadomości na 10 sekund.
  • Na każdą wiadomość przychodzi odpowiedź messageToHostsResult ({ id, hosts }) lub error.
  • Operator widzi wiadomość pod Twoją nazwą presenterName, a host wyświetla powiadomienie, gdy ma włączone ustawienie Powiadomienia.

Lista zdarzeń

Zdarzenia wychodzące (klient → serwer)

ZdarzenieOpis
joinRoomDołączenie do pokoju jako klient API z api: true (zobacz Nawigacja po slajdach)
webActionSterowanie slajdami (zobacz Nawigacja po slajdach)
timerActionSterowanie timerem (zobacz Timer)
presenterMousePozycja wskaźnika laserowego (zobacz Wskaźnik laserowy)
messageToHostsWysłanie wiadomości do operatora hosta (zobacz Wiadomości do hosta)
logoutOpuszczenie pokoju; połączenie pozostaje otwarte i może ponownie dołączyć

Zdarzenia przychodzące (serwer → klient)

ZdarzenieOpis
connectedWysyłane po otwarciu połączenia z { clientId, userId, isAuthenticated }
joinedRoomPomyślnie dołączono do pokoju
clientJoinedKtoś dołączył do pokoju
clientLeftKtoś opuścił pokój
webActionResultwebAction zostało dostarczone do hostów pokoju
timerActionResulttimerAction zostało dostarczone do hostów pokoju
messageToHostsResultmessageToHosts zostało dostarczone do hostów pokoju
clicksEnabledCzy host przyjmuje Twoje polecenia
controlsCo obsługują aplikacja do prezentacji i timer hosta
slideBieżący slajd hosta po poleceniu
countdownCzas na timerze hosta
countdownPhaseFaza timera hosta
messageFromHostWiadomość od operatora hosta
logoutOperator usunął lub zablokował Twoje połączenie (reason: "kicked")
errorKomunikat o błędzie