Location

Locations are points of interest in your app's user interface. Generally, each distinct view or page in your app is its own location.

You can go beyond that and define locations that are as granular as you want. If a page has sections or tabs, each one can be its own location. You can have distinct locations for each cell in a table, or specific paragraphs of text, or even specific timestamps in a video.

When a user interacts with your app's UI, they are marked as present in the location they're interacting with. You associate locations with a whole page using the Cord components Sidebar or PagePresence, and with specific UI elements using PresenceObserver.

When a user places an annotation on a page using a Cord component, the annotation gets a location indicating where it is on the page. Learn more about how to customize this behavior in our guide to improving annotation accuracy.

Locations are represented in Cord as JavaScript objects. The keys must be strings, and the values can be strings, numbers, or booleans.

{
  page: "dashboard",
  video: "welcome.mp4",
  time: 85
}

{
  page: "dashboard",
  video: "welcome.mp4",
  time: 85
}

Cord components that need a location will use the page's URL (including query parameters) if you don't pass one. This may work for some apps, but may result in undesirable behavior for others. For example, two URLs with different tracking parameters will be counted as two separate locations, even though they may point to the same logical page. We recommend always specifying locations in Cord components explicitly.

Partial Matching #

Suppose you have two users, and they are present in these locations:

• { page: "dashboard", section: "top-left" }
• { page: "dashboard", section: "bottom-right" }

Let's say, for example, that you want to put a PresenceFacepile component at the top of the dashboard page that shows all users who are present on the page. What location can you give it that would capture those two users?

The answer is to supply a location of { page: "dashboard" }and also set the partialMatch property to true. Cord components and APIs do exact matching of locations by default, but can be set to do partial matching via the partialMatch property or argument. When partial matching is enabled, if the PresenceFacepile location's key-value pairs are a subset of a user location's key-value pairs, then the user will appear in the facepile.

Thus, a PresenceFacepile with partial matching whose location is { page: "dashboard" } would show the two example users above, but not a user who is present in { page: "reports" }.

A PresenceFacepile whose location is { page: "dashboard", section: "top-left" } would only show the first example user above, but not the second, whether or not partial matching is enabled. It also would not show a user whose location is simply { page: "dashboard" }, even with partial matching.