サインイン

WebSocket リアルタイム

独自のソフトウェアから、リモートのプレゼンリモコンのように Cliqer のルームを操作し、スライド、タイマー、レーザーポインター、ホストへのメッセージを扱えます

wss://cliqer.io/ws に接続すると、独自のソフトウェアやショーコントロールシステムから、リモートのプレゼンリモコンのように Cliqer のルームを操作できます。スライドの切り替え、ホストのタイマーの操作、レーザーポイントでの指し示し、ホストへのメッセージ送信が可能です。アプリは発表者としてルームに参加します。ルームのホストは常に Cliqer デスクトップアプリが務めます。

認証:セッショントークンで接続します。session_token Cookie(ブラウザーが自動的に送信します)、?token= クエリパラメーター、または Authorization: Bearer ヘッダーを使用します。トークンは接続時に検証され、コマンドごとには検証されません。そのため、トークンの有効期限が切れたら、新しいトークンで新しい接続を開き、再度参加してください。トークンなしでも接続はできますが、API は使用できません。チーム API キー(cliqer_...)は REST エンドポイントの認証専用です。このソケットでは、キーはセッショントークンとして扱われません。

接続

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

サーバーは接続のセットアップが完了すると、clientId を含む connected を送信します。何かを送信する前に、必ずこれを待ってください。それより前に届いたメッセージは error で拒否され、接続が閉じられます。


接続とルームのフロー

スライドナビゲーション

独自のソフトウェアから、リモートのプレゼンリモコンのようにルームのスライドを操作できます。アプリは発表者としてルームに参加するため、ホストの発表者リストには presenterName の名前で表示され、ほかの発表者と同じように管理されます。オペレーターはクリックをオフにしたり、削除したり、ブロックしたりできます。

  • セッショントークン(?token=、Authorization: Bearer ヘッダー、または session_token Cookie)で接続します。チーム API キーは REST エンドポイント専用で、このソケットでは使用できません。
  • ルームオーナーのプランに Client API が含まれている必要があります。Presenter、Studio HD、Studio 4K では API アドオンで利用でき、Studio 8K と Enterprise には標準で含まれています。
  • スライドとタイマーのコマンドは、ホストがこの接続からのクリックを許可している間のみ実行されます。

ルームに参加する

{ "type": "joinRoom", "payload": { "room": "ABC123", "presenterName": "Show control", "api": true } }
  • connected イベントの後に送信してください。それより前に届いたものは、サーバーがすべて拒否します。
  • presenterName はホスト側に表示される名前です(デフォルトは API)。アプリは常にルームの発表者であり、ホストになることはありません。
  • コマンドを送信する前に、ペイロードが true の clicksEnabled イベントを待ってください。ホストは接続のセットアップが完了したときにこのイベントを送信し、オペレーターがクリックのオン/オフを切り替えるたびに再度送信します。
  • joinedRoom で受け取った presenterKey を保存し、再接続時に joinRoom で送信してください。これにより、ホスト側でクリックの許可が維持されます。
  • 接続を維持するため、15 秒ごとにテキストフレーム ping を送信してください。サーバーはテキストフレーム 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 を使用してください。ホストは、同じ接続から過去 5 秒以内に受け取ったのと同じ id のコマンドを破棄するため、同じコマンドを再試行しても実行されるのは 1 回だけです。
  • first、last、goto、blackout は、最新の controls イベントの nav にそれらが含まれているホストでのみ実行されます。controls イベントを送信しないホストは next と prev のみに対応します。ルームに複数のホストがいる場合、各ホストは自身が対応するコマンドを実行します。
  • 画面が黒の状態で next または prev を送ると、スライドを移動せずに画面を再表示します。
  • 最後のスライドを超える goto は無視されます。
  • コマンドの送信は、スライドとタイマーのコマンドを合わせて 1 秒あたり最大 10 件までです。また、ホストは 50 ミリ秒以内に繰り返された同じコマンドを破棄します。

各プレゼンテーションアプリの現在の対応状況:

プレゼンテーションアプリnext、prevfirst、lastgotoblackout
Windows 版 PowerPoint対応対応対応対応
Mac 版 PowerPoint対応対応非対応非対応
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 の場合は、ホストの次の controls イベントの blackout も変化します。ホストが実行しないコマンド(クリックがオフの場合、非対応のコマンド、最後のスライドを超える goto)にも結果は返されますが、slide イベントは届きません。

error発生する状況
auth_requiredセッショントークンのない接続で、api: true を指定して joinRoom を送信した
not_api_clientapi: true でルームに参加していない接続、または退出後の接続からコマンドを送信した
invalid_web_action不明な action、または slide、on、id が欠落しているか無効
invalid_timer_action不明なタイマーの action、または minutes や id が欠落しているか無効
invalid_messagetext がない、または 1000 文字を超えるメッセージ
invalid_presenter_mouseポインターの位置が 0 から 1 の範囲外
rate_limited1 秒間にスライドとタイマーのコマンドが 10 件を超えた、または 10 秒間にメッセージが 5 件を超えた
no_hostルームにホストが接続していない
host_update_requiredルーム内のすべてのホストが、API からのコマンドを受け付けられない旧バージョンの Cliqer を実行している
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 に含まれます:

イベントペイロード
clicksEnabledホストがコマンドを受け付ける場合は true、オペレーターがクリックをオフにした場合は 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(残り 1 分未満)、overtime、paused のいずれかで、blink はホストのタイマーが点滅しているかどうか
messageFromHostホストのオペレーターからの返信。ホストへのメッセージを参照

ルーム自体のイベント(clientJoined、clientLeft など)も受信します。使用しないものは無視してください。オペレーターが接続を削除またはブロックした場合は、reason: "kicked" を含む logout を受信します。

タイマー

Stream Deck や Bitfocus Companion が送信するのと同じコマンドで、ホストの Cliqer アプリのタイマーを操作します。

{ "type": "timerAction", "payload": { "action": "set", "minutes": 25, "id": "t1" } }
action動作
startタイマーを開始、または stop の後に再開
stopタイマーを一時停止
resetタイマーを停止し、設定した時間に戻す
plus1、plus2、plus51 分、2 分、5 分を追加
minus1、minus2、minus51 分、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 を実行しているホストはこれを通知せず、タイマーコマンドを無視します。
  • タイマーコマンドには、スライドコマンドと同じルールが適用されます。ホストがこの接続からのクリックを許可している間のみ実行され、1 秒あたり 10 件の上限をスライドコマンドと共有します。
  • ホストのタイマー設定はそのまま適用されます。カウントアップに設定されたタイマーはカウントアップし、接続されたハードウェアタイマーに連動するタイマーは、そのデバイスから時間を取得します。

レーザーポインター

発表者のスマートフォンと同じように、ホストの共有画面にレーザーポイントを表示します。

{ "type": "presenterMouse", "payload": { "mouse": { "x": 0.5, "y": 0.25 } } }
  • x と y は、共有画面の左上隅を基準とした位置で、0 から 1 の範囲で指定します。
  • ポイントを非表示にするには、ペイロードとして { "pressed": false } を送信します。送信しない場合は、最後に位置を送信してから 30 から 90 秒後に消えます。
  • ポイントは、ホストが画面を共有していて、レーザーポインターがオンになっている間のみ表示されます。色は presenterName に応じて決まります。
  • 位置の送信は 1 秒あたり最大 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 文字です。メッセージの送信は 10 秒あたり最大 5 件までです。
  • 各メッセージには、messageToHostsResult({ id, hosts })または error で応答が返されます。
  • オペレーターには presenterName の名前でメッセージが表示され、ホストの通知設定がオンの場合は通知も表示されます。

イベントリファレンス

送信イベント(クライアント → サーバー)

イベント説明
joinRoomapi: true を指定して API クライアントとしてルームに参加(スライドナビゲーションを参照)
webActionスライドの操作(スライドナビゲーションを参照)
timerActionタイマーの操作(タイマーを参照)
presenterMouseレーザーポインターの位置(レーザーポインターを参照)
messageToHostsホストのオペレーターにメッセージを送信(ホストへのメッセージを参照)
logoutルームから退出。接続は開いたままで、再度参加できます

受信イベント(サーバー → クライアント)

イベント説明
connected接続時に { clientId, userId, isAuthenticated } とともに送信
joinedRoomルームへの参加に成功
clientJoined誰かがルームに参加
clientLeft誰かがルームから退出
webActionResultwebAction がルームのホストに配信された
timerActionResulttimerAction がルームのホストに配信された
messageToHostsResultmessageToHosts がルームのホストに配信された
clicksEnabledホストがコマンドを受け付けるかどうか
controlsホストのプレゼンテーションアプリとタイマーが対応する機能
slideコマンド実行後のホストの現在のスライド
countdownホストのタイマーの時間
countdownPhaseホストのタイマーのフェーズ
messageFromHostホストのオペレーターからのメッセージ
logoutオペレーターが接続を削除またはブロックした(reason: "kicked")
errorエラーメッセージ