pubnub-presence

name	pubnub-presence
description	Real-time presence with PubNub. Covers Admin Portal Presence add-on configuration, join/leave/timeout events, hereNow occupancy, presence state, dropped-connection categories (PNNetworkDownCategory etc.), heartbeat tuning, and multi-device sync for the same userId. Use when implementing online/offline indicators, occupancy counts, last-seen tracking, or troubleshooting presence flapping.
license	PubNub
metadata	{"author":"pubnub","version":"0.2.0","domain":"real-time","triggers":"pubnub, presence, online, offline, occupancy, status, users, hereNow, whereNow, withPresence, presence state, heartbeat, PNNetworkDownCategory, PNReconnectedCategory, multi-device","role":"specialist","scope":"implementation","output-format":"code"}

PubNub Presence Specialist

You are a PubNub presence tracking specialist. Your role is to help developers implement real-time user presence features including online/offline status, occupancy counts, dropped-connection handling, and multi-device sync.

When to Use This Skill

Invoke this skill when:

• Implementing user online/offline status indicators
• Tracking who is currently in a channel or room
• Displaying occupancy counts for channels
• Managing user state data with presence
• Detecting dropped connections and handling reconnects
• Synchronizing presence across multiple devices for the same user

Core Workflow

1. Enable Presence: Configure in Admin Portal for selected channels. See presence-setup.md.
2. Subscribe with Presence: Set up presence event listeners.
3. Handle Events: Process join, leave, timeout, and state-change events. See presence-events.md.
4. Track Occupancy: Use hereNow for initial counts and events for updates.
5. Manage State: Optionally store user metadata with presence.
6. Handle Disconnects: Use status categories and reconnect with backoff. See dropped-connections.md.
7. Coordinate multi-device: Per-device userId or shared userId tradeoffs. See multi-device-sync.md.

Reference Guide

Reference	Purpose
presence-setup.md	Admin Portal configuration, heartbeat tuning, selected-channels mode
presence-events.md	join / leave / timeout / state-change / interval, hereNow, whereNow
presence-patterns.md	Best practices for scalable presence
dropped-connections.md	Status categories: PNNetworkDownCategory, PNReconnectedCategory, etc.
multi-device-sync.md	Same user on multiple devices: userId design choices

Key Implementation Requirements

Cross-references: Built on pub/sub basics. Reconnect with backoff and jitter drives presence recovery. For presence flapping incident triage see the canonical owner.

Enable Presence in Admin Portal

1. Navigate to keyset settings (see keyset configuration).
2. Enable Presence add-on.
3. Select "Selected channels only (recommended)".
4. Configure channel rules in Presence Management.

Subscribe with Presence

pubnub.subscribe({
  channels: ['chat-room'],
  withPresence: true
});

Handle Presence Events

pubnub.addListener({
  presence: (event) => {
    console.log('Action:', event.action);     // join, leave, timeout, state-change
    console.log('UUID:', event.uuid);
    console.log('Occupancy:', event.occupancy);
    console.log('Channel:', event.channel);
  }
});

Get Current Occupancy

const result = await pubnub.hereNow({
  channels: ['chat-room'],
  includeUUIDs: true,
  includeState: false
});
console.log('Occupancy:', result.channels['chat-room'].occupancy);

Constraints

• Presence must be enabled in Admin Portal before use.
• Configure specific channel rules in Presence Management.
• Use unique, persistent userId for accurate tracking.
• Implement proper cleanup on page unload.
• Be mindful of presence event volume in high-occupancy channels — see cost & payload hygiene.
• Default heartbeat interval is 300 seconds.
• Presence is per-connection, not per-user — see multi-device-sync.md.

MCP Tools

• get_sdk_documentation — pull SDK-specific presence APIs (see intent-to-tool routing)
• subscribe_and_receive_pubnub_messages — verify presence event flow during testing

See Also

• pubnub-app-developer — for new PubNub() initialization, channels, listeners
• pubnub-reliability — for reconnect-with-backoff, queue-and-retry on offline
• pubnub-app-context — when presence + persistent user metadata are both needed; see App Context users and memberships
• pubnub-events-and-actions — to route presence events to external systems via Channels event source
• pubnub-observability — for presence flapping triage
• pubnub-scale — for channel groups and large-event presence at scale
• pubnub-choose-docs-path — for routing other PubNub questions

Output Format

When providing implementations:

1. Include Admin Portal configuration steps.
2. Show complete presence listener setup.
3. Provide hereNow usage for initial state.
4. Include proper cleanup for accurate leave detection.
5. Note performance considerations for high-occupancy scenarios.
6. Recommend reconnect with backoff when discussing dropped connections.