Betafunction DocumentEditor({documentId, documentType}: DocumentHandle) {
useReportPresence({documentId, documentType})
return <Editor />
}
// The document id stays plain; the perspective selects the version.
useReportPresence({documentId, documentType, perspective: {releaseName: 'autumn'}})
function TitleField({documentId, documentType}: DocumentHandle) {
const [focused, setFocused] = useState(false)
useReportPresence({documentId, documentType, path: focused ? ['title'] : undefined})
return <input onFocus={() => setFocused(true)} onBlur={() => setFocused(false)} />
}
Announces that the current user is in a document, so that other clients in the same project and dataset can show them.
Writing presence is opt-in. Reading it with
usePresenceForDocumentorusePresencenever announces anything, and this hook is the only thing that makes an app visible to others. That includes the Studio, which shares the same presence room and will show these users in its navbar and field indicators.Announcements are throttled, collapsed over a short window, and then repeated every 30 seconds while the user is idle. That repeat is what tells peers the session is still alive, so the intended usage is to mount this hook for as long as the user is in the document. On unmount the location is cleared, leaving the user present in the app but not in any particular document.
The perspective decides which specific document is reported: the draft under
drafts, the published document underpublished, a version under a release. It is taken fromResourceProviderunless you pass one on the handle. That matters for interoperability, because the Studio's field indicators compare the exact id its form is on, so a mismatch shows your user at document level while never lighting up a field.Presence is scoped to a single project and dataset. It is not a list of everyone signed in to your organization.