Presence API Reference

The Presence API allows you to manage and track the presence of participants in a channel. This reference covers the methods and types available for working with presence.

Methods

update()

update(data: any)

Updates the presence data for the current participant.

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

subscribe()

subscribe<T>(event: PresenceEvents | string, callback: PresenceCallback<T>)

Subscribes to a specific presence event. You can use either a string literal or the PresenceEvents enum.

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

// Using PresenceEvents enum
channel.participant.subscribe(PresenceEvents.UPDATE, callback);

// Using string literal
channel.participant.subscribe('presence.update', callback);

unsubscribe()

unsubscribe(event: PresenceEvents | string)

Unsubscribes from a specific presence event. You can use either a string literal or the PresenceEvents enum.

// Using PresenceEvents enum
channel.participant.unsubscribe(PresenceEvents.UPDATE);

// Using string literal
channel.participant.unsubscribe('presence.update');

getAll()

getAll(): PresenceEvent[]

Retrieves all current presence information for the channel.

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

Types

PresenceEvent<T>

Represents a presence event.

type PresenceEvent<T = unknown> = {
  id: string;
  name: string;
  connectionId: string;
  data: T;
  timestamp: number;
};

Field	Type	Description
id	string	Unique identifier for the participant
name	string or null	Name of the participant or null
connectionId	string	Unique identifier for the connection
data	T	Custom data associated with the presence event
timestamp	number	Unix timestamp of when the event occurred

PresenceCallback<T>

Callback function type for presence events.

type PresenceCallback<T = unknown> = (event: PresenceEvent<T>) => void;

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

PresenceEvents

Enum of available presence event types.

enum PresenceEvents {
  JOINED_ROOM = 'presence.joined-room',
  LEAVE = 'presence.leave',
  UPDATE = 'presence.update',
}

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

Usage Example

Here's a complete example demonstrating the usage of the Presence API:

import { PresenceEvents } from '@superviz/realtime';

const channel = await realtime.connect('channel-name');

// Subscribe to presence updates using PresenceEvents enum
const callback = ({ data }) => {
  console.log("Presence update", data);
};
channel.participant.subscribe(PresenceEvents.UPDATE, callback);

// Subscribe to presence updates using string literal
channel.participant.subscribe('presence.joined-room', (event) => {
  console.log("Participant joined", event.data);
});

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

// Unsubscribe from presence updates using PresenceEvents enum
channel.participant.unsubscribe(PresenceEvents.UPDATE);

// Unsubscribe from presence updates using string literal
channel.participant.unsubscribe('presence.joined-room');

// Get all presence information
const presences = channel.participant.getAll();
console.log(presences);

This example shows how to subscribe to presence updates using both the PresenceEvents enum and string literals, update your own presence, unsubscribe from updates, and retrieve all presence information for the channel.