Presence Sets

Similar to other Relaybox operations, "presence" relies on the transmission of data via events. In previous sections, we discussed receiving data based on event subscriptions and rooms.

Presence extends this core functionality by providing connection identification, allowing subscribers to be aware of who else is present in a room at a given point in time.

Presence Sets

Presence sets are groups of connections that are active in a given room. A connection can be part of a presence set in multiple rooms simultaneously. However, when a connection explicitly leaves a room, either intentionally or due to connection issues, it is removed from the corresponding presence set.

Joining a Presence Set

To join a presence set, a connection requires a "clientId." Client IDs are granted at the point of connection either by using an API key or authentication tokens (recommended).

import RelayBox from '@relaybox/client';

const relayBox = new RelayBox({
  apiKey: 'xxxxxxxx.xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxx',
  // Specifying a Client id allows the connection to join a presence set
  clientId: 123
});

await relayBox.connect();

The code above demonstrates the simplest way to connect using a client ID. In practice, this ID will likely be provided via more robust authentication methods involving database or auth service requests, but the end goal is to attach the "clientId" to a connection.

Once a client ID is attached, this connection is permitted to join a presence set for a room.

const myRoom = relayBox.join('myRoom');

// Join the precense set for "myRoom"
await myRoom.presence.join();

Joining a presence set often involves passing data as part of the transmission. This attaches relevant data about the connection in addition to the connection ID.

const myRoom = relayBox.join('myRoom');

const userData = {
  username: 'Bob'
};

// Join the precense set for "myRoom" passing additional data
await myRoom.presence.join(userData);

This additional data sent with the "join" event can then be processed by connections receiving the message.

const myRoom = await relayBox.join('myRoom');

await myRoom.presence.subscribe('join', (data) => {
  console.log(data);

  /*
  {
    event: "join",
    timestamp: "2024-07-13T10:13:28.496Z",
    id: "appId:connectionId",
    data: {
      username: 'Bob'
    }
  }
  */
});

Updating a Presence Set

Alongside the standard "join" and "leave" events, you can also publish a presence "update" event.

Consider a fleet tracking system where a group of vehicles send periodic location-based data, handled in real-time by a fleet navigation system. Vehicle A joins the presence set at 08:00 AM, sending location data every minute to keep the route finder updated. Presence allows the connection to send additional data as an "update" event, allowing the tracking system to attach data, in this case, location coordinates, to the client ID.

const myRoom = await relayBox.join('myRoom');

const userData = {
  registration: 'xxxx xxx',
  latitude: 0.00,
  longitude: 0.01
};

await myroom.presence.update(userData);

Leaving a Presence Set

It's also essential to know how to explicitly leave a presence set.

const myRoom = relayBox.join('myRoom');

await myRoom.presence.leave();

This action removes the connection from the presence set and broadcasts the event to all subscribers. Additionally, if you have previously joined the presence set for a room, the leave event will also be broadcast when you exit the room.

const myRoom = relayBox.join('myRoom');

// Clean up room and broadcast presence "leave" event
await myRoom.leave();

    On this page