Presence enables you to track the online and offline status of users and devices in real time and store custom state information. When you have Presence enabled, PubNub automatically creates a presence channel for each channel. Subscribing to a presence channel or presence channel group will only return presence events.
For any channel, the name of the corresponding presence channel is the channel name followed by
-pnpres. For example, the presence channel for
Presence is also available for channel groups, and follows the same naming convention. For example, the presence channel group for
Receiving presence events
You can enable realtime presence events when you subscribe to channels in two ways: by enabling the
withPresence flag, or by adding individual presence channels to the list of channels. (The flag automatically adds presence channels to the subscribe list.)
Once you have subscribed to a presence channel, the listener starts receiving presence events.
The following presence events are available to you:
- join fires when a user subscribes to a channel
- leave fires when a user unsubscribes from a channel
- timeout fires when a connection to a channel is severed and the subscriber hasn't been seen in 320 seconds (just over 5 minutes). You can customize the timeout interval using the heartbeat and heartbeat interval settings.
- state-change fires anytime the user's state is changed using the state API (function signature varies by SDK)
- interval fires to provide an occupancy count. The default setting for the Presence Interval property is 10 seconds, which is configurable on your Admin Dashboard's Presence add-on panel.
Join event sample
Leave event sample
Timeout event sample
Custom state change event sample
Interval event sample
Requesting on-demand presence status
You can obtain information about the current state of a channel, including a list of unique users currently subscribed to the channel, by calling the
hereNow() function after the connection is established:
Using presence web hooks
Presence Web Hooks provide a means for your server to be notified whenever presence events occur on any channel for your keys. This provides a scalable solution for your server-side application to monitor presence events.
Before you implement the REST endpoints, it's helpful to know what the events' data looks like (content-type is application/json). Here is an example of a
The JSON payload is the same for
state-change, other than the value of the
action object. You would only include the
data object if there was state data involved, but this is everything you need to consider.
For active and inactive, the content-type is
The value of
status will be either
Once your server's REST endpoints are implemented and the PubNub key configuration is in place, you're ready to go.
You may find it useful to provide separate endpoints for active/inactive and join/leave/timeout/state-change events, but there is no requirement to do so.
Working with user state
getState() methods work with user state information.
The state is an object of key/value pairs with any arbitrary data, as long as the data is of type
string. When you set or update the state, PubNub fires a state-change event to other users on the channel.
PubNub stores the state for the time the user is online.
Setting state for a user
setState() to set extra information for a user on a channel.
Getting state for a user
getstate() to get a user's state information.