Presence Basics

Presence gives you visibility into who is currently subscribed to a channel.

In other words, it monitors the subscribers of channels and delivers information on their real-time status. It also lets you:

  • Measure channel occupancy.
  • Monitor and add dynamic custom state information, like profile info, typing indicators, or current location.
  • Use Events & Actions to have PubNub notify your server whenever presence events occur.
User ID / UUID

User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.

When you have Presence enabled on your keyset in the Admin Portal, PubNub automatically creates additional presence equivalents of all channels. These presence channels are named after the main ones but contain an additional -pnpres suffix. Their purpose is to track all presence events about users.

Subscription with Presence

You must create a subscription with Presence enabled to receive Presence events. For more information, refer to each SDK's Publish and Subscribe documentation.

Presence Management

If you want to track Presence only for the selected channels and channel groups, create Presence rules in the Admin Portal as part of the BizOps Workspace.

icon

Ready for your weekly check-in?

Configuration

To use Presence, you must enable and configure it on a chosen app's keyset in the Admin Portal.

Presence in Admin Portal

OptionDescription
Announce MaxA maximum number of occupants in a channel after which you want to receive specific Presence events less frequently. Suppose the number of clients subscribed to a channel goes above this value. In that case, you will no longer receive join, leave, or timeout Presence events, but instead, you'll receive a recurring interval event informing about channel occupancy.
IntervalThe option that relates to the Announce Max setting and specifies how often (in seconds) the interval event fires.
Presence DeltasWhile the interval event specifies how many people subscribed to the channel in a specified amount of time, you may want to know who has joined or left the channel since the last update. Using this option, you'll get two additional fields for every interval event: lists of users who joined and those who left the channel.
Generate Leave on TCP FIN or RSTThis option will detect the connection termination of a network layer and report it as a PubNub leave event. A leave event instead of a timeout event will be generated when a browser tab is closed or an application is force quitted.
Stream FilteringThe option that lets you filter out the Presence events at the client level to receive to the Presence channel only the relevant events (like join events only for a particular User ID).
Active Notice ChannelFor some use cases, you are not concerned about how many occupants you have in the channel or who they are. You only care whether a channel has active subscribers or not. If nobody is subscribed to a channel, you refer to it as an inactive channel, and if there are subscribers, the channel is active. This option lets you specify a channel to receive notifications about channels as their active or inactive state changes.
DebounceA number of seconds to wait before allowing a join event to fire after an explicit leave event. It's a way of smoothing out any rapidly changing state caused by network issues or even deliberate action on the user's part.

Get Online Users in Channel

When a client opens the app, it's often required to discover what other users are already subscribed to that channel (for example, to construct a chat room's online friends list). You can obtain a list of client User IDs

User ID

UTF-8 encoded, unique string of up to 64 characters used to identify a single client (end user, device, or server) that connects to PubNub.
, including clients' state data, and the total occupancy of the channel using the Here Now API.

Once the current state has been fetched, your app can rely on presence events to keep the user state up to date. Go to the Presence Events to learn more.

note
hereNow() cache response time

Note that hereNow() has a 3 second response cache time.

pubnub.hereNow(
{
channels: ["chats.room1", "chats.room2"],
includeState: true
},
function (status, response) {
console.log(status, response);
}
);
Custom user state

You can add custom state information to the users in your application. For more details, refer to Presence State.

Get Subscribed Channels for User

Sometimes it may be necessary for the client app to confirm the channels to which it's currently subscribed. Though this is rarely necessary to do this, except for possibly when you're testing and troubleshooting your app. This can be accomplished with the Where Now API.

pubnub.whereNow({uuid: pubnub.uuid},
function (status, response) {
// handle status, response
}
);

Presence events

Presence events are sent as users come online or go offline from the application. For more details on what they are and how you can receive these events directly from your client, refer to Presence Events.

Last updated on