Tracking user presence

Presence lets you track the online and offline status of users and devices in real-time and store custom state information. When you have Presence enabled in the Admin Portal, PubNub automatically creates equivalents of all channels that monitor and collect all presence events.

For more information, refer to User Presence.

Get user occupancy

Use the hereNow method to get information about the current state of users in a channel. The call returns a list of unique users currently subscribed to the channel.

pubnub.hereNow({
channels: ['ch-1'],
includeUUIDs: true,
includeState: true,
}, (status, response) => {
// handle status, response
});

User state

Users can set dynamic custom state on one or more channels. This custom state persists on a channel as long as the user stays subscribed to that channel. Some examples of custom states are to add your score, game state, or location in an application if it changes frequently.

Use the setState method to set dynamic state for a user on channels. A state is an object of key/value pairs with any arbitrary data, as long as the data is of type int, float, or string. When you set or update the state, PubNub fires a state-change event to other users on the channel.

pubnub.setState({
state: {
mood: 'grumpy',
},
channels: ['main'],
}, (status, response) => {
// handle state setting response
});

You can get state data for any client on a given channel(s) or channel group(s) user the Get State API. This is useful to get the state of other clients based on their UUID.

pubnub.getState(
{
uuid: "john-doe",
channels: ["main"],
channelGroups: ["my_channel_group"]
},
function (status, response) {
// handle status, response
}
);

For more details on working with user state, refer to Setting Custom Presence State.

Presence events

PubNub triggers presence events as users come online or go offline from the application. Clients can receive these events directly, or you can use webhooks on a server to keep a user's online/offline status up to date. Use these events to keep track of users coming and going and the total occupancy of the channel.

EventsDescription
joinFires when a user subscribes to a channel.
leaveFires when a user unsubscribes from a channel.
timeoutFires when a connection to a channel is lost and the subscriber hasn't been seen in 320 seconds (just over 5 minutes).
state-changeFires anytime the user's state is changed using the state API (function signature varies by SDK).
intervalFires to provide an occupancy count. The default setting for the Presence Interval property is 10 seconds, which is configurable on your Admin Portal's Presence add-on panel.

Join event:

{
"channel": "room-1",
"subscription": null,
"actualChannel": null,
"subscribedChannel": "room-1-pnpres",
"action": "join",
"timetoken": "15119466699655811",
"occupancy": 2,
"uuid": "user1",
"timestamp": 1511946669
}

Leave event:

{
"channel": "room-1",
"subscription": null,
"actualChannel": null,
"subscribedChannel": "room-1-pnpres",
"action": "leave",
"timetoken": "15119446002445794",
"occupancy": 1,
"uuid": "user1",
"timestamp": 1511944600
}

Timeout event:

{
"channel": "room-1",
"subscription": null,
"actualChannel": null,
"subscribedChannel": "room-1-pnpres",
"action": "timeout",
"timetoken": "15119519897494311",
"occupancy": 3,
"uuid": "user1",
"timestamp": 1511951989
}

User state change event:

{
"channel": "room-1",
"subscription": null,
"actualChannel": null,
"subscribedChannel": "room-1-pnpres",
"action": "state-change",
"state": {
"mood": "grumpy"
},
"timetoken": "15119477895378127",
"occupancy": 5,
"uuid": "user1",
"timestamp": 1511947789
}

Interval event:

{
"channel": "room-1",
"subscription": null,
"actualChannel": null,
"subscribedChannel": "room-1-pnpres",
"action": "interval",
"timetoken": "15119477895378127",
"occupancy": 2,
"timestamp": 1511947739
}

Presence webhooks

Use presence webhooks to have PubNub notify your server whenever presence events occur on any channel for your keys. This provides a scalable solution for your server-side application to monitor presence events. For more details on these webhooks, refer to the Presence Webhooks documentation.