Σύνδεση

WebSocket σε πραγματικό χρόνο

Ελέγξτε ένα δωμάτιο Cliqer από το δικό σας λογισμικό σαν απομακρυσμένο τηλεχειριστήριο παρουσιάσεων, με διαφάνειες, το χρονόμετρο, δείκτη λέιζερ και μηνύματα προς τον οικοδεσπότη

Συνδεθείτε στο wss://cliqer.io/ws για να ελέγχετε ένα δωμάτιο Cliqer από το δικό σας λογισμικό ή σύστημα show control, όπως με ένα απομακρυσμένο τηλεχειριστήριο παρουσιάσεων: αλλάζετε διαφάνειες, χειρίζεστε το χρονόμετρο του οικοδεσπότη, δείχνετε με μια κουκκίδα λέιζερ και στέλνετε μηνύματα στον οικοδεσπότη. Η εφαρμογή σας συμμετέχει στο δωμάτιο ως ομιλητής· το ίδιο το δωμάτιο φιλοξενείται πάντα από την εφαρμογή Cliqer για υπολογιστή.

Πιστοποίηση: συνδεθείτε με ένα διακριτικό συνεδρίας (session token): το cookie session_token (τα προγράμματα περιήγησης το στέλνουν αυτόματα), μια παράμετρο ερωτήματος ?token= ή μια κεφαλίδα Authorization: Bearer. Το διακριτικό ελέγχεται κατά τη σύνδεση, όχι σε κάθε εντολή, οπότε όταν λήξει ανοίξτε νέα σύνδεση με νέο διακριτικό και μπείτε ξανά στο δωμάτιο. Χωρίς διακριτικό μπορείτε να συνδεθείτε, αλλά δεν μπορείτε να χρησιμοποιήσετε το API. Τα κλειδιά API ομάδας (cliqer_...) πιστοποιούν μόνο τα endpoints REST· σε αυτό το socket ένα κλειδί δεν αποτελεί διακριτικό συνεδρίας.

Σύνδεση

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

Ο διακομιστής στέλνει connected με το clientId σας μόλις ολοκληρώσει τη ρύθμιση της σύνδεσης. Περιμένετε αυτό το μήνυμα πριν στείλετε οτιδήποτε: ένα μήνυμα που φτάνει νωρίτερα απορρίπτεται με error και η σύνδεση κλείνει.


Σύνδεση & ροή δωματίου

Πλοήγηση διαφανειών

Ελέγξτε τις διαφάνειες ενός δωματίου από το δικό σας λογισμικό, όπως με ένα απομακρυσμένο τηλεχειριστήριο παρουσιάσεων. Η εφαρμογή σας συμμετέχει στο δωμάτιο ως ομιλητής, οπότε ο οικοδεσπότης τη βλέπει στη λίστα ομιλητών με το presenterName της και τη διαχειρίζεται όπως κάθε ομιλητή: ο χειριστής μπορεί να απενεργοποιήσει τα κλικ της, να την αφαιρέσει ή να την αποκλείσει.

  • Συνδεθείτε με ένα διακριτικό συνεδρίας (?token=, μια κεφαλίδα Authorization: Bearer ή το cookie session_token). Τα κλειδιά API ομάδας λειτουργούν μόνο στα endpoints REST, όχι σε αυτό το socket.
  • Το πρόγραμμα του κατόχου του δωματίου πρέπει να περιλαμβάνει το Client API: το πρόσθετο API στα Presenter, Studio HD και Studio 4K, ενώ στα Studio 8K και Enterprise περιλαμβάνεται ήδη.
  • Οι εντολές διαφανειών και χρονομέτρου εκτελούνται μόνο όσο ο οικοδεσπότης επιτρέπει κλικ από τη σύνδεσή σας.

Συμμετοχή στο δωμάτιο

{ "type": "joinRoom", "payload": { "room": "ABC123", "presenterName": "Show control", "api": true } }
  • Στείλτε το μετά το συμβάν connected: ο διακομιστής απορρίπτει οτιδήποτε φτάνει πριν από αυτό.
  • Το presenterName είναι το όνομα που βλέπει ο οικοδεσπότης (προεπιλογή API). Η εφαρμογή σας είναι πάντα ομιλητής στο δωμάτιο, ποτέ οικοδεσπότης του.
  • Περιμένετε ένα συμβάν clicksEnabled με payload true πριν στείλετε εντολές. Ο οικοδεσπότης το στέλνει μόλις ρυθμίσει τη σύνδεσή σας και ξανά κάθε φορά που ο χειριστής ενεργοποιεί ή απενεργοποιεί τα κλικ σας.
  • Κρατήστε το presenterKey από το joinedRoom και στείλτε το στο joinRoom όταν επανασυνδέεστε, ώστε ο οικοδεσπότης να διατηρήσει την άδεια κλικ σας.
  • Στέλνετε το πλαίσιο κειμένου ping κάθε 15 δευτερόλεπτα για να παραμένει ανοιχτή η σύνδεση. Ο διακομιστής απαντά με το πλαίσιο κειμένου pong (όχι JSON).

Αποστολή εντολών

{ "type": "webAction", "payload": { "action": "goto", "slide": 5, "id": "a3" } }
actionΕπιπλέον πεδίοΤι κάνει
nextΕπόμενη διαφάνεια (ή κίνηση)
prevΠροηγούμενη διαφάνεια (ή κίνηση)
firstΠρώτη διαφάνεια
lastΤελευταία διαφάνεια
gotoslide: ακέραιος αριθμός από 1 έως 9999Μετάβαση σε αυτή τη διαφάνεια
blackouton: true ή falseΜαύρισμα της οθόνης ή επανεμφάνισή της
  • Το id είναι προαιρετικό: 1 έως 64 γράμματα, ψηφία, _, ., : ή -. Επιστρέφεται στο αποτέλεσμα. Χρησιμοποιείτε νέο id για κάθε εντολή: ο οικοδεσπότης απορρίπτει μια εντολή της οποίας το id έχει ήδη λάβει από τη σύνδεσή σας τα τελευταία 5 δευτερόλεπτα, οπότε μια επανάληψη της ίδιας εντολής εκτελείται μία φορά.
  • Τα first, last, goto και blackout εκτελούνται μόνο σε οικοδεσπότη του οποίου το πιο πρόσφατο συμβάν controls τα αναφέρει στο nav. Ένας οικοδεσπότης που δεν στέλνει συμβάν controls υποστηρίζει μόνο next και prev. Με περισσότερους οικοδεσπότες στο δωμάτιο, κάθε οικοδεσπότης εκτελεί τις εντολές που υποστηρίζει.
  • Ένα next ή prev ενώ η οθόνη είναι μαύρη την εμφανίζει ξανά χωρίς μετακίνηση.
  • Ένα goto πέρα από την τελευταία διαφάνεια αγνοείται.
  • Στέλνετε το πολύ 10 εντολές ανά δευτερόλεπτο, μαζί οι εντολές διαφανειών και χρονομέτρου. Ο οικοδεσπότης απορρίπτει επίσης μια επανάληψη της ίδιας εντολής μέσα σε 50 χιλιοστά του δευτερολέπτου.

Τι υποστηρίζει σήμερα κάθε εφαρμογή παρουσιάσεων:

Εφαρμογή παρουσιάσεωνnext, prevfirst, lastgotoblackout
PowerPoint σε WindowsΝαιΝαιΝαιΝαι
PowerPoint σε MacΝαιΝαιΌχιΌχι
KeynoteΝαιΌχιΌχιΝαι
Google Slides (με συνδεδεμένη επέκταση προγράμματος περιήγησης)ΝαιΝαιΌχιΌχι
vMixΝαιΌχιΌχιΌχι
Ενεργό παράθυροΝαιΌχιΌχιΌχι

Το συμβάν controls είναι η ζωντανή απάντηση για τον οικοδεσπότη που ελέγχετε: διαβάζετε το nav από αυτό και όχι από αυτόν τον πίνακα.

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

Αποτελέσματα και συμβάντα

Κάθε εντολή λαμβάνει απάντηση με webActionResult ή error.

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

Το hosts είναι ο αριθμός των οικοδεσποτών στους οποίους παραδόθηκε η εντολή. Η απόδειξη ότι εκτελέστηκε είναι το επόμενο συμβάν slide του οικοδεσπότη· το blackout αλλάζει επίσης το blackout στο επόμενο συμβάν controls του οικοδεσπότη. Μια εντολή που ο οικοδεσπότης δεν εκτελεί (απενεργοποιημένα κλικ, εντολή που δεν υποστηρίζει, goto πέρα από την τελευταία διαφάνεια) λαμβάνει αποτέλεσμα αλλά όχι συμβάν slide.

errorΠότε
auth_requiredjoinRoom με api: true σε σύνδεση χωρίς διακριτικό συνεδρίας
not_api_clientΕντολή από σύνδεση που δεν έχει μπει σε δωμάτιο με api: true ή αφού αποχώρησε
invalid_web_actionΆγνωστο action ή slide, on ή id που λείπει ή δεν είναι έγκυρο
invalid_timer_actionΆγνωστο action χρονομέτρου ή minutes ή id που λείπει ή δεν είναι έγκυρο
invalid_messageΜήνυμα χωρίς text ή μεγαλύτερο από 1000 χαρακτήρες
invalid_presenter_mouseΘέση δείκτη εκτός του εύρους 0 έως 1
rate_limitedΠερισσότερες από 10 εντολές διαφανειών και χρονομέτρου σε ένα δευτερόλεπτο ή περισσότερα από 5 μηνύματα σε 10 δευτερόλεπτα
no_hostΚανένας οικοδεσπότης δεν είναι συνδεδεμένος στο δωμάτιο
host_update_requiredΌλοι οι οικοδεσπότες στο δωμάτιο εκτελούν παλαιότερη έκδοση του Cliqer που δεν δέχεται εντολές από το API
api_not_in_planΤο πρόγραμμα του κατόχου του δωματίου δεν περιλαμβάνει το Client API

Τα σφάλματα περιέχουν ένα ευανάγνωστο message και, όταν ήταν σωστά διαμορφωμένα, το action και το 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" } }

Τα συμβάντα από έναν οικοδεσπότη φέρουν το id του στο hostId:

ΣυμβάνPayload
clicksEnabledtrue όταν ο οικοδεσπότης δέχεται τις εντολές σας, false όταν ο χειριστής απενεργοποίησε τα κλικ σας
controls{ app, nav, blackout, timer }: η εφαρμογή παρουσιάσεων, οι επιπλέον εντολές διαφανειών που υποστηρίζει (first, last, goto, blackout), αν η οθόνη είναι μαύρη και αν ο οικοδεσπότης δέχεται εντολές χρονομέτρου
slide{ number, current, total, title, notes } μετά από κάθε εντολή που εκτέλεσε ο οικοδεσπότης (το number είναι "4/12", το total είναι null όταν η εφαρμογή δεν το αναφέρει) ή null όταν ο οικοδεσπότης δεν έχει ανοιχτή παρουσίαση
countdownΟ χρόνος που δείχνει το χρονόμετρο του οικοδεσπότη, π.χ. "4:59" ("-0:12" σε υπέρβαση χρόνου), κάθε δευτερόλεπτο όσο τρέχει, ή null όταν σταματά
countdownPhase{ phase, blink }: το phase είναι idle, talk, warning (απομένει λιγότερο από ένα λεπτό), overtime ή paused και το blink δείχνει αν το χρονόμετρο του οικοδεσπότη αναβοσβήνει
messageFromHostΑπάντηση από τον χειριστή του οικοδεσπότη, δείτε Μηνύματα προς τον οικοδεσπότη

Λαμβάνετε επίσης τα συμβάντα του ίδιου του δωματίου (clientJoined, clientLeft και άλλα)· αγνοήστε όσα δεν χρησιμοποιείτε. Αν ο χειριστής αφαιρέσει ή αποκλείσει τη σύνδεσή σας, λαμβάνετε logout με reason: "kicked".

Χρονόμετρο

Χειριστείτε το χρονόμετρο στην εφαρμογή Cliqer του οικοδεσπότη με τις ίδιες εντολές που στέλνει ένα Stream Deck ή το Bitfocus Companion.

{ "type": "timerAction", "payload": { "action": "set", "minutes": 25, "id": "t1" } }
actionΤι κάνει
startΈναρξη του χρονομέτρου ή συνέχιση μετά από stop
stopΠαύση του χρονομέτρου
resetΔιακοπή του χρονομέτρου και επιστροφή στον χρόνο στον οποίο είχε ρυθμιστεί
plus1, plus2, plus5Προσθήκη 1, 2 ή 5 λεπτών
minus1, minus2, minus5Αφαίρεση 1, 2 ή 5 λεπτών
preset5, preset10, preset15, preset20Διακοπή του χρονομέτρου και ρύθμιση σε 5, 10, 15 ή 20 λεπτά
setΔιακοπή του χρονομέτρου και ρύθμιση σε minutes, ακέραιο αριθμό από 1 έως 999
  • Κάθε εντολή λαμβάνει απάντηση με timerActionResult ({ action, id, hosts }, με το hosts όπως στις διαφάνειες) ή error. Η απόδειξη ότι εκτελέστηκε είναι το επόμενο συμβάν countdown ή countdownPhase του οικοδεσπότη.
  • Το χρονόμετρο λειτουργεί μόνο σε οικοδεσπότη του οποίου το πιο πρόσφατο συμβάν controls έχει timer: true. Οι οικοδεσπότες με παλαιότερη έκδοση του Cliqer δεν το ανακοινώνουν και αγνοούν τις εντολές χρονομέτρου.
  • Οι εντολές χρονομέτρου ακολουθούν τους ίδιους κανόνες με τις εντολές διαφανειών: ο οικοδεσπότης τις εκτελεί μόνο όσο επιτρέπει κλικ από τη σύνδεσή σας και μοιράζονται το όριο των 10 εντολών ανά δευτερόλεπτο.
  • Οι ρυθμίσεις χρονομέτρου του οικοδεσπότη ισχύουν ως έχουν: ένα χρονόμετρο ρυθμισμένο να μετρά προς τα πάνω μετρά προς τα πάνω, και ένα χρονόμετρο που ακολουθεί συνδεδεμένο χρονόμετρο υλικού παίρνει τον χρόνο του από εκείνη τη συσκευή.

Δείκτης λέιζερ

Εμφανίστε μια κουκκίδα λέιζερ στην κοινόχρηστη οθόνη του οικοδεσπότη, όπως κάνει το τηλέφωνο ενός ομιλητή.

{ "type": "presenterMouse", "payload": { "mouse": { "x": 0.5, "y": 0.25 } } }
  • Τα x και y είναι η θέση στην κοινόχρηστη οθόνη από την πάνω αριστερή γωνία της, από 0 έως 1.
  • Στείλτε { "pressed": false } ως payload για να κρύψετε την κουκκίδα. Διαφορετικά εξαφανίζεται 30 έως 90 δευτερόλεπτα μετά την τελευταία θέση σας.
  • Η κουκκίδα εμφανίζεται μόνο όσο ο οικοδεσπότης μοιράζεται μια οθόνη και έχει ενεργοποιημένο τον Δείκτη λέιζερ. Το χρώμα της ακολουθεί το presenterName σας.
  • Στέλνετε το πολύ 30 θέσεις ανά δευτερόλεπτο. Οι επιπλέον θέσεις απορρίπτονται χωρίς σφάλμα και δεν υπάρχει συμβάν αποτελέσματος.

Μηνύματα προς τον οικοδεσπότη

Στείλτε ένα μήνυμα στον χειριστή του οικοδεσπότη. Εμφανίζεται στη συνομιλία ομιλητών του οικοδεσπότη, όπως ένα μήνυμα από το τηλέφωνο ενός ομιλητή, και οι απαντήσεις του χειριστή επιστρέφουν ως 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"

Απάντηση από τον οικοδεσπότη:

{
  "type": "messageFromHost",
  "payload": {
    "fromClientId": "host_abc123",
    "fromPresenterName": "Stage PC",
    "originalPayload": { "text": "Thanks, got it" }
  },
  "hostId": "host_abc123"
}
  • Το text έχει 1 έως 1000 χαρακτήρες. Στέλνετε το πολύ 5 μηνύματα κάθε 10 δευτερόλεπτα.
  • Κάθε μήνυμα λαμβάνει απάντηση με messageToHostsResult ({ id, hosts }) ή error.
  • Ο χειριστής βλέπει το μήνυμα με το presenterName σας και ο οικοδεσπότης εμφανίζει ειδοποίηση όταν η ρύθμιση Ειδοποιήσεις είναι ενεργή.

Αναφορά συμβάντων

Εξερχόμενα συμβάντα (Πελάτης → Διακομιστής)

ΣυμβάνΠεριγραφή
joinRoomΣυμμετοχή σε δωμάτιο ως πελάτης API με api: true (δείτε Πλοήγηση διαφανειών)
webActionΈλεγχος διαφανειών (δείτε Πλοήγηση διαφανειών)
timerActionΈλεγχος χρονομέτρου (δείτε Χρονόμετρο)
presenterMouseΘέση δείκτη λέιζερ (δείτε Δείκτης λέιζερ)
messageToHostsΑποστολή μηνύματος στον χειριστή του οικοδεσπότη (δείτε Μηνύματα προς τον οικοδεσπότη)
logoutΑποχώρηση από το δωμάτιο· η σύνδεση παραμένει ανοιχτή και μπορεί να μπει ξανά

Εισερχόμενα συμβάντα (Διακομιστής → Πελάτης)

ΣυμβάνΠεριγραφή
connectedΑποστέλλεται κατά το άνοιγμα με { clientId, userId, isAuthenticated }
joinedRoomΕπιτυχής συμμετοχή στο δωμάτιο
clientJoinedΚάποιος μπήκε στο δωμάτιο
clientLeftΚάποιος αποχώρησε από το δωμάτιο
webActionResultΈνα webAction παραδόθηκε στους οικοδεσπότες του δωματίου
timerActionResultΈνα timerAction παραδόθηκε στους οικοδεσπότες του δωματίου
messageToHostsResultΈνα messageToHosts παραδόθηκε στους οικοδεσπότες του δωματίου
clicksEnabledΑν ένας οικοδεσπότης δέχεται τις εντολές σας
controlsΤι υποστηρίζουν η εφαρμογή παρουσιάσεων και το χρονόμετρο ενός οικοδεσπότη
slideΗ τρέχουσα διαφάνεια ενός οικοδεσπότη μετά από μια εντολή
countdownΟ χρόνος στο χρονόμετρο ενός οικοδεσπότη
countdownPhaseΗ φάση του χρονομέτρου ενός οικοδεσπότη
messageFromHostΜήνυμα από τον χειριστή του οικοδεσπότη
logoutΟ χειριστής αφαίρεσε ή απέκλεισε τη σύνδεσή σας (reason: "kicked")
errorΜήνυμα σφάλματος