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.

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.

Ready for your weekly check-in?

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.

JavaScript

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

Swift

pubnub.hereNow(on: ["chats.room1", "chats.room2"]), and: [],
  includeUUIDs: true, also: true { result in
    switch result {
      case let .success(response):
        print("Successful hereNow Response: \(response)")

      case let .failure(error):
        print("Failed hereNow Response: \(error.localizedDescription)")
    }
})

Objective-C

[self.pubnub hereNowForChannel: @[@"chats.room1", "chats.room2"]
    withVerbosity:PNHereNowState
    completion:^(PNPresenceChannelHereNowResult *result, PNErrorStatus *status) {
  // parse the HereNow result parameter
}];

Java

pubnub.hereNow()
  .channels(Arrays.asList("chats.room1", "chats.room2"))
  .includeState(true)
  .async(result -> {
      result.onSuccess(res -> {
          for (PNHereNowChannelData channelData : res.getChannels().values()) {
              System.out.println("---");
              System.out.println("channel:" + channelData.getChannelName());
              System.out.println("occupancy: " + channelData.getOccupancy());
              System.out.println("occupants:");

              for (PNHereNowOccupantData occupant : channelData.getOccupants()) {
                  System.out.println("userId: " + occupant.getUuid()
                          + " state: " + occupant.getState());
              }

show all 20 lines

C#

pubnub.HereNow()
  .Channels(new string[] {"chats.room1", "chats.room2"})
  .IncludeState(true)
  .Execute(new PNHereNowResultEx((result, status) => {
    if (status.Error) {
      Console.WriteLine("HereNow error: " + status);
    }
    else if (result.Channels != null && result.Channels.Count > 0) {
      foreach (KeyValuePair<string, PNHereNowChannelData> kvp in result.Channels) {
        PNHereNowChannelData channelData = kvp.Value;
        Console.WriteLine("---");
        Console.WriteLine("channel:" + channelData.ChannelName);
        Console.WriteLine("occupancy:" + channelData.Occupancy);
        Console.WriteLine("Occupants:");

show all 27 lines

Python

def here_now_callback(result, status):
  if status.is_error():
    print("here_now error: %s" % status)
    return

  for channel_data in result.channels:
    print("---")
    print("channel: %s" % channel_data.channel_name)
    print("occupancy: %s" % channel_data.occupancy)

    print("occupants: %s" % channel_data.channel_name)

    for occupant in channel_data.occupants:
      print("user_id: %s, state: %s" % (occupant.user_id, occupant.state))

show all 19 lines

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.

JavaScript

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

Swift

pubnub.whereNow(for: pubnub.uuid) { result in
  switch result {
  case let .success(response):
    print("Successful WhereNow Response: \(response)")

  case let .failure(error):
    print("Failed WhereNow Response: \(error.localizedDescription)")
  }
}

Objective-C

[self.pubnub whereNowUUID:self.pubnub.uuid withCompletion:
      ^(PNPresenceWhereNowResult *result, PNErrorStatus *status) {
  if (!status) {
    NSLog(status);
  }
  else {
    NSLog(result);
  }
}];

Java

pubnub.whereNow()
  .async(result -> { /* check result */ });

C#

pubnub.WhereNow()
  .Execute(new PNWhereNowResultExt((result, status) => {
    if (status.isError) {
      Console.WriteLine(status.ErrorData.Information);
    }
    else {
      Console.WriteLine(result);
    }
  }
));

Python

envelope = pubnub.where_now().sync()

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.