Observe users present at a location

How to use the presence API to observe users present at a location


Overview #

This method allows you to observe users who are present at a particular location, including live updates.
React:
import { presence } from '@cord-sdk/react';
const present = presence.useLocationData(
  { page: "https://cord.com", block: "id123" },
  { exclude_durable: true },
);
return (
  <>
    {present.map((user) => <div>{user.id} is present!</div>)}
  </>
);
Vanilla JavaScript:
const ref = window.CordSDK.presence.observeLocationData(
  { page: "https://cord.com", block: "id123" },
  (present) => present.forEach(
    (d) => console.log(`${d.id} is present!`)
  ),
  { exclude_durable: true },
);
// ... Later, when updates are no longer needed ...
window.CordSDK.presence.unobserveLocationData(ref);
import { presence } from '@cord-sdk/react';
const present = presence.useLocationData(
  { page: "https://cord.com", block: "id123" },
  { exclude_durable: true },
);
return (
  <>
    {present.map((user) => <div>{user.id} is present!</div>)}
  </>
);
Copy

Available Data #

The API provides an array of objects, each of which has the following fields:


ephemeral #

object
Contains information about the user's ephemeral presence. The location array can be empty if the user is not currently present at the requested location.

This is an object with the following fields:


locations #

Location[]

id #

string
The user ID of the user this presence information is for.

durable #

object
Contains information about the user's durable presence. Undefined if the user does not have a durable presence set. The location and timestamp will be for the user's most recently-set matching durable presence record (which may not be for the requested location if using the partial_match option).

This is an object with the following fields:


location #

Location

timestamp #

Date

What this function returns #

An array of objects, one for each user present at the location which was passed to this hook. Each object will contain the fields described under "Available Data" above. The component will automatically re-render if any of the data changes, i.e., this data is always "live".

Arguments this function takes #


location #

required
Location
The location to fetch presence information for.

options #

optional
ObservePresenceOptions
Options that control which presence records are returned.

This is an object with the following fields:


exclude_durable #

optional
boolean
When true, only return ephemeral presence records.
This value defaults to false.

partial_match #

optional
boolean
When true, returns users in any partially matching location, rather than in only the specific location given.
This value defaults to false.

Ask Cordy