Presence API Reference

Participant presence allows clients to monitor and manage the status of other participants currently in the channel. This feature offers robust functionality for tracking and updating participant status.

Usage

To use the presence feature, you need to access the participant property from the channel instance. This property provides methods to update, subscribe, and unsubscribe from presence events.

import { Realtime } from '@superviz/realtime'

const realtime = new Realtime('DEVELOPER_KEY', {
  participant: {
    id: 'PARTICIPANT_ID',
  },
});

const channel = await realtime.connect('YOUR_CHANNEL_NAME');

const participant = channel.participant;

Methods

getAll()

To get a list of all participants' presence information in the channel use the getAll() method, like the following:

const presences = channel.participant.getAll();
console.log(presences);

subscribe()

To receive presence update notifications, you can subscribe to specific events using the subscribe() method. You can use either a string literal or the PresenceEvents enum.

JavaScript

const callback = (event) => {
  console.log("Presence update", event.data);
};

channel.participant.subscribe(PresenceEvents.UPDATE, callback);

TypeScript

import { PresenceEvent } from '@superviz/realtime'

const callback = (event: PresenceEvent) => {
  console.log("Presence update", event.data);
};

channel.participant.subscribe('presence.update', callback);

unsubscribe()

If you no longer want to receive presence update notifications, you can unsubscribe from specific events, using either a string literal or the PresenceEvents enum.

JavaScript

channel.participant.unsubscribe('presence.update');

TypeScript

import { PresenceEvents } from '@superviz/realtime'

channel.participant.unsubscribe(PresenceEvents.UPDATE);

update()

You can update the participant's presence information using the update method, like the following:

channel.participant.update({ name: "John", status: "online" });

Events

The presence feature emits events to notify you when a participant joins, leaves, or updates their presence information. You can subscribe to these events using the subscribe() method.

JOINED_ROOM

The JOINED_ROOM is dispatched when a participant joins the channel. Here is an example of how to catch the dispatched event:

JavaScript

const callback = (event) => {
  console.log("Participant joined", event.data);
};

channel.participant.subscribe('presence.joined-room', callback);

TypeScript

import { PresenceEvents, PresenceEvent } from '@superviz/realtime'

const callback = (event: PresenceEvent) => {
  console.log("Participant joined", event.data);
};

channel.participant.subscribe(PresenceEvents.JOINED_ROOM, callback);

On the callback function, you will receive the following argument:

Type	Description
PresenceEvent<T>	The presence event object that contains the participant's presence data.

LEAVE

The LEAVE event is triggered when a participant leaves the channel. Here is an example of how to catch the dispatched event:

JavaScript

const callback = (event) => {
  console.log("Participant left", event.data);
};

channel.participant.subscribe('presence.leave', callback);

TypeScript

import { PresenceEvents, PresenceEvent } from '@superviz/realtime'

const callback = (event: PresenceEvent) => {
  console.log("Participant left", event.data);
};

channel.participant.subscribe(PresenceEvents.LEAVE, callback);

On the callback function, you will receive the following argument:

Type	Description
PresenceEvent<T>	The presence event object that contains the participant's presence data.

UPDATE

The UPDATE event is dispatched when a participant's presence data is updated. Here is an example of how to catch the dispatched event:

JavaScript

const callback = (event) => {
  console.log("Participant updated", event.data);
};

channel.participant.subscribe('presence.update', callback);

TypeScript

import { PresenceEvents, PresenceEvent } from '@superviz/realtime'

const callback = (event: PresenceEvent) => {
  console.log("Participant updated", event.data);
};

channel.participant.subscribe(PresenceEvents.UPDATE, callback);

On the callback function, you will receive the following argument:

Type	Description
PresenceEvent<T>	The presence event object that contains the participant's presence data.

Types

PresenceEvent<T>

This is the representation of the data structure of the event dispatched by the presence. It contains the following properties:

Field	Type	Description
id	string	Participant ID responsible for triggering the event. This value can be nullable, meaning that the event wasn't dispatched by a participant.
name	string or null	Participant name responsible for triggering the event. This value can be nullable, meaning that the event wasn't dispatched by a participant.
connectionId	string	The connection ID of the connection used to publish the message. This value can be nullable, meaning that the event wasn't dispatched by a participant.
data	T	Custom data associated with the presence event.
timestamp	number	The timestamp of the message, is represented as a numerical value.

PresenceCallback<T>

The PresenceCallback<T> type represents a callback function for presence events.

Parameter	Type	Description
event	PresenceEvent<T>	The presence event object

PresenceEvents

Type: enum

The enumerable represents the available presence events. These are the possible values:

Event	Value	Description
JOINED_ROOM	'presence.joined-room'	Triggered when a participant joins the room.
LEAVE	'presence.leave'	Triggered when a participant leaves the room.
UPDATE	'presence.update'	Triggered when a participant's presence data is updated.