Skip to main content

Presence Functions

The Presence adapter handles connecting to the CometD server for push notifications and updating the participants' presence in a simulation.

Importing the adapter​

To use the functions of the Presence adapter, import it as shown:
import { presenceAdapter } from 'epicenter-libs';

The presenceAdapter namespace exports functions that make calls to the Presence API.

learn more

For descriptions of the objects used by the presence adapter functions, read Presence entities.

Retrieve​

Retrieve group presence​

To retrieve presence information (i.e., if users are currently online) for a specific group, use the forGroup() function.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The forGroup() function:

  • Constructs a GET request to the endpoint /presence/group/{groupKey}.
  • Returns a list of online users in the specified group.
  • Accepts optional routing options for customizing the API call.
Function signature
export async function forGroup(
    groupKey: string,
    optionals: RoutingOptions = {}
): Promise<Presence[]>

Parameters​

  • groupKey (string): The key associated with the group whose presence information should be retrieved.
  • optionals (RoutingOptions object): Optional overrides for the network call.

Return value​

A promise that resolves to an array of Presence objects.

Usage example​

import { presenceAdapter } from 'epicenter-libs';

// Get list of users online in a specific group
presenceAdapter.forGroup('0000017dd3bf540e5ada5b1e058f08f36489');

Retrieve world presence​

To retrieve presence information (i.e., if users are currently online) for a specific world, use the forWorld() function.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The forWorld() function:

  • Constructs a GET request to the endpoint /presence/world/{worldKey}.
  • Returns a list of online users in the specified world.
  • Accepts optional routing options for customizing the API call.
Function signature
export async function forWorld(
    worldKey: string,
    optionals: RoutingOptions = {},
): Promise<Presence[]>

Parameters​

  • worldKey (string): The key associated with the world whose presence information should be retrieved.
  • optionals (RoutingOptions object): Optional overrides for the network call.

Return value​

A promise that resolves to an array of Presence objects.

Usage example​

import { presenceAdapter } from 'epicenter-libs';

// Get list of users online in a specific world
presenceAdapter.forWorld('0000017a445032dc38cb2cecd5fc13708314');

Update user presence​

Connect user​

To mark the current user as online with the CometD server, use the connect() function.

Subscribing to any CometD channel will implicitly connect the user as well. This function is convenient when you don't need to utilize the channels expect specifically for presence.

Logging the user out with the authAdapter.logout() function automatically disconnects them.

Function description​

The connect() function:

  • Initiates a handshake with the CometD server, establishing a connection.
  • Returns a promise that resolves once the connection attempt completes.
Function signature
export async function connect(): Promise<void>

Return value​

A promise that resolves to void when the connection to the CometD server is successfully established.

Usage example​

import { presenceAdapter } from 'epicenter-libs';

// Establish connection with CometD server for presence purposes
presenceAdapter.connect();

Disconnect user​

To remove the current user's presence and disconnect from the CometD server, use the disconnect() function.

Calling authAdapter.logout() will automatically trigger this disconnection.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The disconnect() function:

  • Terminates the CometD connection for the current user.
  • Removes the user's presence from the associated group, if a groupKey is available.
  • Accepts optional network call overrides.
  • Returns a promise that resolves once all cleanup operations have settled.
Function signature
export async function disconnect(optionals: RoutingOptions): Promise<void>

Parameters​

Return value​

A promise that resolves to void once the disconnection and presence cleanup are complete.

Usage example​

import { presenceAdapter } from 'epicenter-libs';

// Disconnect user from CometD and remove group presence
await presenceAdapter.disconnect({
  headers: { 'X-Custom-Header': 'value' }
});