How-to

Portal How-to: Enabling Presence

3 min read • Oliver Carson on May 26, 2022

What is Presence?

Presence enables you to track the online and offline status of users and devices in real time. PubNub triggers Presence events to monitor channel occupancy, when a user has joined or left a channel, typing, mood, or status indicators, current location, and profile information. Enabling Presence on your keyset in the Admin Portal will automatically create additional presence equivalents of all channels to track these presence events about users.

When presence events are triggered for a channel, there are two different modes the channel will be in: Announce and Interval. The mode is determined by occupancy count (total actively subscribed clients on that channel). Announce is the default mode and the join, leave, timeout and state-change events are sent to subscribed clients when they’re triggered. Once the channel has reached the announced max number (handled in the portal setting discussed below), the channel goes into interval mode. This mode will replace sending join, leave and timeout events with interval events and are sent every few seconds based on the Interval setting (set in the Presence setting discussed below). If the user enables the “Presence Deltas” setting, interval events will also include who has joined, left or timed out in that interval.

Use webhooks (callbacks) to have PubNub notify your server whenever presence events occur on any channel for your keys, especially if you have a large number of channels or where the actual channel names may be dynamic and continuously changing. Provide a REST POST endpoint for the Presence webhook settings if you wish to receive these callbacks on your server. It is recommended to have at least two different REST POST endpoints: one for Channel Active/Inactive Webhooks, and then another for the rest of the Presence webhooks, due to differences in payload structures.

Follow Along

Watch the video below or follow the step-by-step instructions to learn how to enable Presence in your PubNub keyset. Need extra information? Check out PubNub’s official documentation on Presence to learn more about how to implement Presence in your own application.

Step-by-Step

  1. Login to the Admin Portal.

  2. Click on the apps tab on the left hand side of the portal.

  3. Click on an application. You will be brought to the keysets page for this application.

  4. Click on a keyset. You will be brought to the configuration page for this keyset.

  5. Enable Presence by clicking on the slider to turn it on. A pop-up will require that you enter in “ENABLE”. Enter in “ENABLE” in all caps and then press the “Enable” button.

  6. Presence Event Settings. You can leave the default settings for presence functionality to work in your application, but the following Presence Event settings allow you customize and control events:

    1. Announce Max: Specify the maximum number of occupants in the Announce channel mode before switching to the Interval channel mode. 

    2. Interval: Specifies the number of seconds between each interval event in the Interval channel mode.

    3. Presence Deltas: If enabled, will have interval events in the Interval channel mode include information about who has joined, left, or timed out (list of UUIDs).

    4. Generate Leave on TCP FIN or RST: If enabled, PubNub will generate a leave event if the client closes the browser rather than sending the leave event when the user timeouts.

    5. Stream Filtering: If enabled, ensures Presence metadata is included in events published to the presence channels. The Subscription Stream Feature can then be used to ensure that Presence events are not filtered out when using filters on a channel.

  7. Presence Webhook Settings. These are not required for basic presence functionality to work in your application, but are necessary to receive events on your server.

    1. Active Notice Channel: Specify the PubNub channel where active and inactive channel notifications are published.

    2. Channel Active Webhook: Triggers the HTTP(s) endpoint when channel occupancy changes from 0 to 1.

    3. Channel Inactive Webhook: Triggers the HTTP(s) endpoint when channel occupancy changes from 1 to 0.

    4. Presence Join Webhook: Triggers the HTTP(s) endpoint when a user subscribes to a channel.

    5. Presence Leave Webhook: Triggers the HTTP(s) endpoint when a user unsubscribes from a channel.

    6. Presence Timeout Webhook: Triggers the HTTP(s) endpoint when a user timeout from a channel.

    7. Presence State Change Webhook: Triggers the HTTP(s) endpoint when presence state changes for a user.

    8. Presence Interval Webhook: Triggers the HTTP(s) endpoint for interval events.

    9. Debounce: The amount of time in seconds to wait before allowing implicit “joins” after an explicit “leave”.  

  8. Click on Save Changes to save these updated changes.

0