Link copied to clipboard!

Presence

Our presence library contains tools for tracking where in your application your users are and which users are located in a particular place.

Cord tracks two types of presence: ephemeral and durable.

Ephemeral presence is where a user is located at the current instant. You would use this to track online status in a chat application or where a user’s cursor is in a realtime editing application. In this library, we sometimes refer to ephemeral presence records as the user’s location.

A user can be in multiple places at the same time (such as if they have multiple browser tabs open). An ephemeral presence record expires after a short time unless it’s sent again. You can explicitly clear an ephemeral presence record when the user leaves a location. Ephemeral presence is comparatively cheap to track and can be updated frequently.

Durable presence is where a user has been located historically. You would typically use this to show which pages in your application a user has visited.

Durable presence is tracked for each location independently. Durable presence is comparatively expensive to track. It should generally be updated at most once a minute for each location.

Mark the user as present

window.CordSDK.presence.setPresent(location, options)

Marks the user as present at the given location.

Usage

window.CordSDK.presence.setPresent({
  page: "https://cord.com",
  block: "id123",
});

Types

type SetPresentOptions = {
  durable?: boolean;
  absent?: boolean;
  exclusive_within?: Location;
};

function setPresent(location: Location, options: SetPresentOptions = {}): void;

Options

Option Type Description
durable boolean optional When true, this is a durable presence update; otherwise, it is an ephemeral presence update.
absent boolean optional When true, this is an absence update, meaning that the user has just left this location. If the user is currently present at that location, it is cleared; otherwise, nothing happens. This cannot be used with a durable presence update.
exclusive_within location optional This update will clear any other ephemeral presence record with the same exclusive-within as a side effect. If not provided, it defaults to location.

Get the users present at a location

window.CordSDK.presence.getPresent(matcher, options)

Returns a promise containing the set of users present at a location.

If a user has multiple durable presence records that match the matcher, the one with the latest timestamp is returned.

Usage

await window.CordSDK.presence.getPresent({ page: "https://cord.com" });

Types

type GetPresentOptions = {
  exclude_durable?: boolean;
  exact_match?: boolean;
};

type UserLocationData = {
  id: string;
  ephemeral?: {
    locations: Location[] | null;
  };
  durable?: {
    location: Location;
    timestamp: Date;
  };
};

async function getPresent(
  matcher: Location,
  options: GetPresentOptions = {}
): Promise<UserLocationData[]>;

Options

Option Type Description
exclude_durable boolean optional When true, only return ephemeral presence records.
exact_match boolean optional When true, returns only users on the specific location given, rather than any matching location.

Listen for location changes

window.CordSDK.presence.addListener(listener, matcher, options)

window.CordSDK.presence.removeListener(listenerRef)

Listen for user presence changes that match the given matcher. If any user’s ephemeral presence record changes to a matching value, or their durable presence is updated, an update will be sent to the listener. Each update will only include either a durable or ephemeral presence update; if both are updated at the same time, two calls will be made to each listener.

If a user stops having any ephemeral location that matches the matcher, an update will be sent with the locations field set to null, not an empty array.

Usage

const listenerRef = window.CordSDK.presence.addListener(
  (update) => {
    console.log(`${update.id} is at ${update.location}.`);
    processUpdate(update);
  },
  { page: "https://cord.com" }
);
window.CordSDK.presence.removeListener(listenerRef);

Types

type AddListenerOptions = {
  exact_match?: boolean;
};

type UserLocationData = {
  id: string;
  ephemeral?: {
    locations: Location[] | null;
  };
  durable?: {
    location: Location;
    timestamp: Date;
  };
};

type PresenceListener = (update: UserLocationData) => void;

type ListenerRef = unknown;

function addListener(
  listener: PresenceListener,
  matcher: Location,
  options: AddListenerOptions = {}
): ListenerRef;

function removeListener(ref: ListenerRef): void;

Options

Option Type Description
exact_match boolean optional When true, only match users on the specific location given, rather than any matching location.

In this section