Api Reference
Subscriptions
Live subscriptions
PresenceKit uses Server-Sent Events (SSE) with optional REST polling. transport: "auto" is the default and recommended browser setting.
One user: subscribePresence
import { createPresenceClient } from "@iconical/presencekit";
const stop = createPresenceClient().subscribePresence(
"123456789012345678",
{
onUpdate(data) {
console.log(data.presence?.status);
},
onError(error) {
console.error(error.message);
},
},
{
transport: "auto",
intervalMs: 15_000,
onTransportChange(mode) {
console.log("Connection:", mode);
},
},
);
// Cleanup is mandatory when the consumer no longer needs updates.
stop();Several users: subscribePresences
const stop = createPresenceClient().subscribePresences(
["123456789012345678", "234567890123456789"],
{
onUpdate(batch) {
for (const [id, person] of Object.entries(batch.presences)) {
console.log(id, person.presence?.status);
}
},
onError(error) {
console.error(error);
},
},
{ transport: "auto" },
);
// Later: stop();Single and batch subscribers return an unsubscribe function. This core API does not automatically clean up subscriptions inside framework components; use React, Vue, or Svelte for lifecycle-aware integrations.
Options
| Option | Values | Behavior |
|---|---|---|
transport | "auto" (default), "sse", "poll" | auto tries streaming, then polling fallback |
intervalMs | Number, default 15000 | Interval between polling requests, minimum 5000 |
onTransportChange | (mode) => void | Receives connecting, sse, poll, or stopped |
transport: "sse" requires browser EventSource; unlike auto, it does not silently fall back to polling. transport: "poll" works without EventSource. SSE events arrive as the service publishes them; intervalMs doesn't throttle SSE.
The SDK detects disconnected/stalled streams, switches to polling in auto mode, and periodically attempts SSE recovery. A sharing revocation stops that subscription instead of continuing to fetch stale data.
Limits and performance
subscribePresencesaccepts 1–25 unique IDs in each direct API request.- To display larger/dynamic rosters with connection sharing, use the connection manager.
- Always clean up when navigating away to avoid unnecessary network activity.
Was this page helpful?