Backend WebSocket Guide

Connecting To WebSocket (Live Update)

This document explains how to setup the websocket connection with the backend in order to get live updates. The backend uses short-lived tickets for the socket handshake such that authentication of the JWT-token is possible. For the following examples we will be using the xp-service's websocket endpoints.

Flow Overview

1. Call POST /xp-websocket/ticket with that JWT to get a one-time ticket.
2. Immediately open a Socket.IO connection to the /xp-websocket namespace, passing the ticket in auth.
3. Listen for the xp-given event. This event will occur when a user is awarded XP.

Step 1 - Get a ticket

async function getSocketTicket(jwt: string): Promise<string> {
  const res = await fetch('/xp-websocket/ticket', {
    method: 'POST',
    headers: { Authorization: `Bearer ${jwt}` },
  });

  if (!res.ok) {
    throw new Error('Failed to get websocket ticket');
  }

  const { ticket } = await res.json();
  return ticket;
}

Step 2 - Open a connection using the ticket

import { io, Socket } from 'socket.io-client';

async function connectXpSocket(jwt: string): Promise<Socket> {
  const ticket = await getSocketTicket(jwt);

  const socket = io(`${API_BASE}/xp-websocket`, {
    auth: { ticket },
  });

  return socket;
}

Step 3 - Listen for XP event

socket.on('xp-given', (amount: number) => {

...
});