Presence Observer
Enable presence on specific areas
When to use
The PresenceObserver component observes user interaction on its DOM subtree, and marks the current user as present in the location when interaction is detected. The observer has no visual effect on the page.
The observer always registers the user as absent if the document is not currently visible per the Document.visibilityState API.
This component pairs well with:
How to use
By itself this component does not show who is present. To display this, use <PresenceObserver />together with the <PresenceFacepile /> component.
import { PresenceObserver } from "@cord-sdk/react";
export const Example = () => (
<>
// The PresenceObserver tracks and marks users as present in the
// location when user interaction is detected
<PresenceObserver location={{ "page": "index", "section": "content" }}>
<div id="content">
<p>lorem ipsum</p>
</div>
</PresenceObserver>
// The PresenceFacepile displays who is present at the location
<PresenceFacepile
location={{ "page": "index", "section": "content" }}
excludeViewer={false}
maxUsers={7}
/>
</>
);Copy
Properties
location
optional
string
When the user interacts with the DOM elements within
the
<PresenceObserver>, they will be marked as present at this
location in Cord's backend. This value defaults to the current URL.durable
optional
boolean
When set to
true, every user will be able to see
the presence indicator for any user (within the same org) who has
ever been at this location at any point in the past.When set to
false, Cord will only show the users who are
present at the same location at the same time.The default is set to
false.presentEvents
optional
object
An array of event types that Cord should listen for
to determine if the user is present at the
location.Cord marks presence and absence based on JavaScript events like
mouseenter. To do this, Cord uses a set of default event
listeners that cover the majority of cases. You may find that
you need to set additional event listeners to correctly capture
a user's presence within your app.For each event type you list, Cord will automatically create an
event listener (by calling
addEventListener(<event type>, ()
=> { ... })). When these events fire, Cord will pick up the
event and mark the user as present in the current location.Example:
['scroll', 'mousemove'].The default is set to
['mouseenter', 'focusin'].absentEvents
optional
object
As with presentEvents, this value is an array of
event types that Cord should listen for to determine if the user
has left the
location.For each event type you list, Cord will automatically create an
event listener (by calling
addEventListener(<event type>, ()
=> { ... })). When these events fire, Cord will pick up the
event and mark the user as absent in the current location.Example:
['blur'].The default is set to
['mouseleave', 'focusout'].initialState
optional
boolean
A
true or false value to tell Cord whether
or not the viewing user is present in the location.This is necessary if the user is present at page load but may
not yet have triggered any of the "present" DOM events that
would cause them to be marked as present. For example, if the
user loads a page, but doesn't move their mouse or use their
keyboard, Cord will not automatically know that they're present
on the page.
This value is useful in situations where you have many
<PresenceObserver> elements in the page and you want to
surface that the user is present in a particular one at page load.observeDocument
optional
boolean
When
true, presence will be determined by whether
or not the current document is visible, rather than based on the
"present" and "absent" DOM events. Setting this to true means
that presentEvents, absentEvents, and initialState
value will be ignored.The main situation in which you'd want to use this property is
when other events (like cursor and keyboard events) are not
capturing user presence accurately. A common case here is on
very short pages where the majority of the visible screen is
an empty window. In these situations, you may find that the
user doesn't generate any mouse events since their cursor
isn't within the element.
In the majority of such cases, you should consider using the
<PagePresence> component instead, because it provides both
a <PresenceObserver> and a <PresenceFacepile> in a
single component.You may still want a
<PresenceObserver> with observeDocument
set to true if you want to record presence on a page but not
surface it. That is to say – you want to observe presence, but
you don't want to show a facepile. This is sometimes the case
when you want to record presence in one place but surface it in another place.The default is set to
false.onChange
optional
function
Callback invoked when presence state changes. This
callback will receive a
true or false value as an argument
indicating whether or not the user is present at the location.