Link copied to clipboard!
Mobile navigation button - closed state

Presence API

The details behind the client-side Javascript API and the usage of the presence API


Presence

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

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 present in multiple locations at the same time (such as if they have multiple browser tabs open). An ephemeral presence record expires after a short time, and it can also be cleared explicitly 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    
durable default: false optional When true, this is a durable presence update; otherwise, it is an ephemeral presence update.
absent default: false 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 default: location optional In addition to its usual effect, this update will clear any other ephemeral presence record with the same exclusive-within. 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    
exclude_durable default: false optional When true, only return ephemeral presence records.
exact_match default: false optional When true, returns only users in the specific location given, rather than any partially 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    
exact_match default: false optional When true, only match users on the specific location given, rather than any partially matching location.