The details behind the client-side Javascript API and the usage of the presence API
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.
window.CordSDK.presence.setPresent(location, options)
Marks the user as present at the given location.
window.CordSDK.presence.setPresent({
page: "https://cord.com",
block: "id123",
});
// exported by @cord-sdk/types
type SetPresentOptions = {
durable?: boolean;
absent?: boolean;
exclusive_within?: Location;
};
function setPresent(location: Location, options: SetPresentOptions = {}): void;
| 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. |
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.
await window.CordSDK.presence.getPresent({ page: "https://cord.com" });
// exported by @cord-sdk/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[]>;
| 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. |
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.
const listenerRef = window.CordSDK.presence.addListener(
(update) => {
if (update.durable) {
console.log(`${update.id} is at ${update.durable.location}`);
} else if (update.ephemeral) {
if (update.ephemeral.locations) {
console.log(`${update.id} is present at ${update.ephemeral.locations[0]}`);
} else {
console.log(`${update.id} is no longer here`);
}
}
processUpdate(update);
},
{ page: "https://cord.com" }
);
window.CordSDK.presence.removeListener(listenerRef);
// exported by @cord-sdk/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;
| Option | ||
|---|---|---|
exact_match |
default: false optional |
When true, only match users on the specific location given, rather than any partially matching location. |