Presence State

Clients can set a dynamic custom state for their users on one or more channels and store it on a channel as long as the user stays subscribed.

Some examples of custom states are to add your score, game state, or location to an application if it changes frequently.

The state is transient data (it's not persisted anywhere). When the client disconnects, the state data is lost. If you require a client's state to be restored on reconnect, be sure to cache that data locally on the client. For information on how to persist data forever, refer to the App Context documentation.

PubNub also triggers presence state-change events anytime the user's state is modified. Clients can receive these events by subscribing to presence channels. Refer to Presence Events for more details.

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.

Set Presence State

You can set state data for a User ID on a given channel(s) or channel group(s). By default, the User ID is the current client's User ID when this API is invoked. When setting the state on a channel group, it propagates that state to all channels contained in that channel group.

JavaScript

pubnub.setState(
  {
    state: {"mood":"pumped", "isTyping":false},
    channels: ["chats.room1"],
    channelGroups: ["cg_user123_friends"]
  },
  function (status, response) {
    if (status.isError) {
      console.log(status);
    }
    else {
      console.log(response);
    }
  }
);

Swift

pubnub.setPresence(
  state: ["mood": "pumped", "workingFrom": "Home"],
  on: ["chats.room1"],
  and: ["cg_user123_friends"]
) { result in
  switch result {
    case let .success(response):
      print("Successful Set State Response: \(response)")

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

Objective-C

[self.pubnub setState: @{@"mood": @"pumped", @"workingFrom": @"Home"}
      forUUID:self.pubnub.uuid onChannel: @"chats.room1"
      withCompletion:^(PNClientStateUpdateStatus *status) {
    // handle status
}];

Java

JsonObject state = new JsonObject();
state.addProperty("mood", "pumped");
state.addProperty("workingFrom", "Home");

pubnub.setPresenceState()
  .channels(Arrays.asList("chats.room1"))
  .channelGroups(Arrays.asList("cg_user123_friends"))
  .state(state)
  .async(result -> { /* check result */ });

C#

Dictionary<string, object> state = new Dictionary<string, object>();
state.Add("mood", "pumped");
state.Add("workingFrom", "Home");

pubnub.SetPresenceState()
  .Channels(new string[] {"chats.room1"})
  .ChannelGroups(new string[] {"cg_user123_friends"})
  .State(myState)
  .Execute(new PNSetStateResultExt((result, status) => {
    if (status.IsError()) {
      Console.WriteLine("SetPresenceState error:" + status);
    }
    else {
      Console.WriteLine("SetPresenceState success:" + result);
    }

show all 17 lines

Python

my_state = {"mood": "pumped", "workingFrom": "Home"}

envelope = pubnub.set_state()\
  .channels(["chats.room1"]) \
  .channel_groups(["cg_user123_friends"])\
  .state(my_state)\
  .sync()

When you set the state for a client, the existing state is overwritten. Therefore, if you need to update part of the state, you must pass the complete state data payload. For this reason, it's best to keep your state data payloads from getting too large.

Get Presence State

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

JavaScript

pubnub.getState(
  {
    uuid: "anotherClientUserID",
    channels: ["chats.room1"],
    channelGroups: ["cg_user123_friends"]
  },
  function (status, response) {
    // handle status, response
  }
);

Swift

pubnub.getPresenceState(
  for: "anotherClientUserId",
  on: ["chats.room1"],
  and: ["cg_user123_friends"]
) { result in
  switch result {
  case let .success(response):
    print("Successful Get State Response: \(response)")

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

Objective-C

 [self.pubnub stateForUUID:@"anotherClientUUID" onChannel:@"chats.room1"
      withCompletion:^(PNChannelClientStateResult *result, PNErrorStatus *status) {

  if (!status) {

  }
  else {

  }
}];

Java

pubnub.getPresenceState()
  .channels(Arrays.asList("chats.room1"))
  .channelGroups(Arrays.asList("cg_user123_friends"))
  .uuid("anotherClientUserId")
  .async(result -> { /* check result */ });

C#

pubnub.GetPresenceState()
  .Channels(new string[] {"chats.room1"})
  .Uuid(clientUserId)
  .Execute(new PNGetStateResultExt((result, status) => {
    if (status.IsError()) {
      Console.WriteLine("GetPresenceState error:" + status);
    }
    else {
      Console.WriteLine("GetPresenceState success:" + result);
    }
  }
));

Python

envelope = pubnub.get_state()\
  .uuid("anotherClientUserId")\
  .channels(["chats.room1"])\
  .sync()