Skip to content

Websockets API Documentation

Jump to bottom
sonsoleslp edited this page Aug 19, 2020 · 1 revision

The Websockets API allows to connect web applications (compatible with the ws/wss protocol) to Escapp in real-time, allowing participants not only to solve puzzles from outside Escapp but also to synchronize their progress with their team mates and to receive notifications in real-time (messages from the teacher, changes in the leaderboard, new puzzles solved by their team members, new hints obtained by their team members, etc.) Add a custom footer

Connection

In order to connect to the WebSockets API you need the socket.io library. You can add it by inserting this line in your HTML.

<script src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/2.3.0/socket.io.slim.js"></script>

Then, you need to establish the connection:

var socket = io(SERVER_URL, {query: {
    "escapeRoom": ESCAPE_ROOM_ID,
    "email": STUDENT_EMAIL,
    "token": STUDENT_TOKEN,
    // Optional (if you don't have the token)
    "password": STUDENT_PASSWORD
 }});

The SERVER_URLshould be using the ws:// protocol in development and the wss:// protocol in production.

NOTE

In order to establish a connection to the Websockets API for an escape room participant, no HTTP sessions with any other user should be open in Escapp in the same browser. Take into account that the API is only for participants, so you need to provide student credentials in order to make use (even in testing mode) of the API.

Outgoing messages

Messages sent from the client to the server through the Websockets API.

In order to send these messages you can use the emit function exposed by the socket object:

socket.emit("MESSAGE_NAME", payload);

You just need to provide the message name and the payload (an object with specific keys and values depending on the message).

Solve a puzzle

Submits an answer to a puzzle on behalf of the whole team

Message type: SOLVE_PUZZLE

Payload:

Key Description
puzzleOrder Order that the puzzle occupies in the escaper room puzzle list
sol Answer to the puzzle provided by the player

Request a hint

Requests a hint on behalf of the whole team

Message type: REQUEST_HINT

Payload:

Key Description
status Whether they should obtain a hint or not. If yes, the value is completed, if not the value should be failed
score The score obtained in the hint quiz (100 if there is no quiz)
category The hint category (if any)

Start playing

Starts playing the escape room on behalf of the whole team. If attendance is taken individually, only the players that log in to the escape room (via API or through the platform) will be considered present

Message type: START_PLAYING

Payload: None

Incoming messages

Messages sent from the server to the client through the Websockets API. In order to receive these messages you can use the on function exposed by the socket object and specify which message you want to listen to:

socket.on("MESSAGE_NAME", (payload)=>{
	append(payload);
});

Automatic messages

Messages generated by the socket.io library

Connected

The connection to the socket server was established correctly

Message type: connect

Payload: None

Disconnected

The connection to the socket server was finished

Message type: disconnect

Payload: None

Error

An error took place on the server side

Message type: error

Payload: Error message

Connection Error

There was an error connecting to the server

Message type: connect_error

Payload:

Generic messages

Custom message from the teacher

Custom notification sent by the teacher. It can be sent to the team, to the shift participants, or to the whole escape room participants

Message type: MESSAGE

Payload:

Key Description
msg Custom message

Individual messages

Messages sent to individual participants

Initial information

Message type: INITIAL_INFO

Payload:

Key Description
code Response code. OK if everything goes fine. NOK if something fails
authentication Authentication code. Check the REST API docs for more info
token User token
participation Participation code. Check the REST API docs for more info
msg Message indicating whether there was an error
erState Escape room state object including the number of puzzles solved, the leaderboard, the progress, etc.
connectedMembers Number of team members currently connected to the Websocket API

Team messages

Messages that are specific to a single team

Team member joined

A new team member joined the escape room

Message type: JOIN

Payload:

Key Description
username E-mail of the member that joined the room
connectedMembers Number of currently connected members (including the new one)

Team member left

A team member left the escape room

Message type: LEAVE

Payload:

Key Description
username E-mail of the member that left the room
connectedMembers Number of currently connected members (after departure)

Start the escape room

Response to the START_PLAYING message (whether sent via the Websocket API, the REST API, or by manually clicking the Start button on the Escapp web platform). It is received any time a team attempts to start playing the escape room (whether authorized or not)

Message type: TEAM_STARTED

Payload:

Key Description
code Response code. OK if everything goes fine. NOK if something fails
authentication Authentication code. Check the REST API docs for more info
participation Participation code. Check the REST API docs for more info
msg Message indicating whether there was an error
erState Escape room state object including the number of puzzles solved, the leaderboard, the progress, etc.

Team received a hint

Response to a hint request by any team member

Message type: HINT_RESPONSE

Payload:

Key Description
code Response code. OK if everything goes fine. NOK if something fails
authentication Authentication code. Check the REST API docs for more info
participation Participation code. Check the REST API docs for more info
hintOrder Number of hint received
puzzleOrder Number of puzzle to which the hint received belongs
category Category to which the hint belongs
msg Hint content

Team solved a puzzle

Response to a puzzle answer submission by any team member

Message type: PUZZLE_RESPONSE

Payload:

Key Description
code Response code. OK if everything goes fine. NOK if something fails
authentication Authentication code. Check the REST API docs for more info
participation Participation code. Check the REST API docs for more info
correctAnswer true if the submitted answer was correct, false otherwise
puzzleOrder Order that the puzzle occupies in the escaper room puzzle list
msg Message explaining the result obtained
erState Escape room state object including the number of puzzles solved, the leaderboard, the progress, etc.
content Team interface content necessary to solve the next puzzle

Shift messages

Messages that all the participants of a shift receive.

Team joined the escape room

A new team has joined the current shift of the escape room

Message type: JOIN_TEAM

Payload:

Key Description
teamId Id of the team that just joined
ranking Leaderboard content

Team left the escape room

A team has left the current shift of the escape room

Message type: LEAVE_TEAM

Payload:

Key Description
teamId Id of the team that just left
ranking Leaderboard content

Participant joined the escape room

A new participant of another team has joined the current shift of the escape room

Message type: JOIN_PARTICIPANT

Payload:

Key Description
username E-mail of the participant that just joined
teamId Id of the team to which the new participant belongs
ranking Leaderboard content

Participant left the escape room

A participant of another team has left the current shift of the escape room

Message type: LEAVE_PARTICIPANT

Payload:

Key Description
username E-mail of the participant that just left
teamId Id of the team to which the participant belongs
ranking Leaderboard content

Shift starts

The teacher has initiated the shift

Message type: START

Payload: None

Shift stops

The teacher has stopped the shift

Message type: STOP

Payload: None

Leapfrogging

There has been a change in the leaderboard

Message type: TEAM_PROGRESS

Payload: None

Key Description
teamId Id of the team that has moved positions
puzzleOrder Number of puzzle solved by them that has triggered this change
ranking Leaderboard content
Clone this wiki locally