Presence Methods

The presence methods in the Cerebellum SDK allow you to manage presence information for a specific channel. Presence information is used to track the online status of users in a channel, enabling features such as presence-based messaging and presence-based notifications.

enterPresenceSet

enterPresenceSet(
  channelName: string,
  state: State
): void

Description

Enters the user into the presence set of the specified channel. This method allows you to notify the server and other clients that a user has joined the channel, along with any associated state information.

Arguments

• channelName: string
  • Description: The name of the channel to which the user is entering the presence set.
• state: State
  • Description: An object representing the state information associated with the user. The state can contain any key-value pairs as needed.

Return Type

• void
  • Description: This method does not return a value.

Example

cerebellum.enterPresenceSet("general", { username: "alice", status: "online" });

Explanation

• In this example, the user is entering the presence set for the channel "general", with state information indicating the username and status. This information will be broadcast to other users in the channel.

---

leavePresenceSet

leavePresenceSet(channelName: string): void

Description

Leaves the presence set of the specified channel. This method notifies the server and other clients that a user is no longer in the presence channel.

Arguments

• channelName: string
  • Description: The name of the channel from which the user is leaving the presence set.

Return Type

• void
  • Description: This method does not return a value.

Example

cerebellum.leavePresenceSet("general");

Explanation

• In this example, the user is leaving the presence set for the channel "general". Other users will be informed that the user is no longer present in the channel.

---

getPresenceSetMembers

getPresenceSetMembers(channelName: string): Promise<State[]>

Description

Retrieves the current members in the presence set of the specified channel. This method allows you to get the list of users currently in the channel and their associated state information.

Note this is a promise that will resolve with the current members in the presence set.

Arguments

• channelName: string
  • Description: The name of the channel whose presence set members are to be retrieved.

Return Type

• Promise<State[]>

  • Description: Returns a promise that resolves to an array of State objects representing the members of the presence set.
  • Note that the State interface is defined as follows, however it will always contain a socketId property, to uniquely identify the users in the presence set:

• State Interface:

  interface State {
    [key: string]: string;
    socketId: string;
  }
  • Description: An object where the keys and values are user-defined and can contain any relevant information about the user.

Example

const presenceMembers = await cerebellum.getPresenceSetMembers("general");

console.log("Current members in the presence set:", members);

Explanation

• In this example, getPresenceSetMembers is called with the channel name "general". The returned promise resolves to an array of state objects, each representing a member of the presence set.

---

subscribeToPresenceJoins

subscribeToPresenceJoins(channelName: string, callback: (state: State) => void): void

Description

Subscribes to presence join events for a specified channel. This method allows you to receive notifications when a user joins the presence set of the channel.

Arguments

• channelName: string
  • Description: The name of the channel for which to subscribe to presence join events.
• callback: (state: State) => void
  • Description: A callback function that will be invoked when a user joins the presence set. The function receives a State object representing the state information of the user who joined.

Callback Argument

• state: State
  • Description: The callback function receives a State object representing the state information of the user who joined. The State interface is defined as follows:
  • Note that the State interface is defined as follows, however it will always contain a socketId property, to uniquely identify the users in the presence set:
• State Interface:

  interface State {
    [key: string]: string;
    socketId: string;
  }
  • Description: An object where the keys and values are user-defined and can contain any relevant information about the user.

Return Type

• void   - Description: This method does not return a value.

Example

cerebellum.subscribeToPresenceJoins("general", (state) => {
  console.log("User joined with state:", state);
});

Explanation

• In this example, subscribeToPresenceJoins is used to listen for join events in the channel "general". When a user joins, the provided callback function is executed with the state information of the new user.

---

subscribeToPresenceUpdates

subscribeToPresenceUpdates(channelName: string, callback: (state: State) => void): void

Description

Subscribes to presence update events for a specified channel. This method allows you to receive notifications when the state information of a user in the presence set is updated.

Arguments

• channelName: string

  • Description: The name of the channel for which to subscribe to presence update events.

• callback: (state: State) => void

  • Description: A callback function that will be invoked when a user's state is updated in the presence set. The function receives a State object representing the updated state information.
  • Note that the State interface is defined as follows, however it will always contain a socketId property, to uniquely identify the users in the presence set:

• State Interface:

  interface State {
    [key: string]: string;
    socketId: string;
  }

• Description: An object where the keys and values are user-defined and can contain any relevant information about the user.

Return Type

• void   - Description: This method does not return a value.

Example

cerebellum.subscribeToPresenceUpdates("general", (state) => {
  console.log("User state updated:", state);
});

Explanation

• In this example, subscribeToPresenceUpdates is used to listen for updates in the presence set of the channel "general". When a user's state is updated, the provided callback function is executed with the new state information.

---

subscribeToPresenceLeaves

subscribeToPresenceLeaves(channelName: string, callback: (state: State) => void): void

Description Subscribes to presence leave events for a specified channel. This method allows you to receive notifications when a user leaves the presence set of the channel.

Arguments

• channelName: string
  • Description: The name of the channel for which to subscribe to presence leave events.
• callback: (state: State) => void
  • Description: The callback function that was originally passed to the subscribeToPresenceLeaves method. This will deregister the callback from the event listeners.

Return Type

• void   - Description: This method does not return a value.

Example

cerebellum.subscribeToPresenceLeaves("general", (state) => {
  console.log("User left with state:", state);
});

Explanation

• In this example, subscribeToPresenceLeaves is used to listen for leave events in the channel "general". When a user leaves, the provided callback function is executed with the state information of the user who left.

---

unsubscribeFromPresenceJoins

unsubscribeFromPresenceJoins(channelName: string, callback: (state: State) => void): vo
id

Description

Unsubscribes from presence join events for a specified channel. This method removes a previously registered callback that was listening for join events.

Arguments

• channelName: string
  • Description: The name of the channel from which to unsubscribe from presence join events.
• callback: (state: State) => void
  • Description: The callback function that was previously registered to listen for join events. This function will be removed from the event listeners.

Return Type

• void
  • Description: This method does not return a value.

Example

const onJoin = (state) => {;
  console.log("User joined with state:", state);
};

cerebellum.unsubscribeFromPresenceJoins("general", onJoin);

Explanation

• In this example, unsubscribeFromPresenceJoins is used to remove the callback onJoin from listening for join events in the channel "general".

---

unsubscribeFromPresenceUpdates

unsubscribeFromPresenceUpdates(channelName: string, callback: (state: State) => void): void

Description

Unsubscribes from presence update events for a specified channel. This method removes a previously registered callback that was listening for presence update events.

Arguments

• channelName: string
  • Description: The name of the channel from which to unsubscribe from presence update events.
• callback: (state: State) => void
  • Description: The callback function that was previously registered to listen for update events. This function will be removed from the event listeners.

Return Type

• void   - Description: This method does not return a value.

Example

const onUpdate = (state) => {
  console.log("User state updated:", state);
};

cerebellum.unsubscribeFromPresenceUpdates("general", onUpdate);

Explanation

• In this example, unsubscribeFromPresenceUpdates is used to remove the callback onUpdate from listening for presence update events in the channel "general".

---

unsubscribeFromPresenceLeaves

unsubscribeFromPresenceLeaves(channelName: string, callback: (state: State) => void): void

Description Unsubscribes from presence leave events for a specified channel. This method removes a previously registered callback that was listening for leave events.

Arguments

• channelName: string
  • Description: The name of the channel from which to unsubscribe from presence leave events.
• callback: (state: State) => void
  • Description: The callback function that was previously registered to listen for leave events. This function will be removed from the event listeners.

Return Type

• void
  • Description: This method does not return a value.

Example

const onLeave = (state) => {
  console.log("User left with state:", state);
};

cerebellum.unsubscribeFromPresenceLeaves("general", onLeave);

Explanation

• In this example, unsubscribeFromPresenceLeaves is used to remove the callback onLeave from listening for leave events in the channel "general".