Users & Devices

All clients have a notion of a user, a device, or both. Uniquely identifying either is an important concept concerning how those interact with the PubNub Platform. Clients are entities that connect to the platform via applications. In most applications, users are actual people who connect from the application.

The relationship between users and devices is important because a single user can have multiple devices that use your application. Does your application allow the simultaneous use of multiple devices, or does it prevent such a scenario? The answer to this question will determine how you uniquely identify users and their devices.

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.

User ID Usage

A User ID is a 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. User IDs are also important for other features like Presence and Message Persistence to work as expected.

User ID is mandatory

You must set the User ID to establish a connection to PubNub and ensure your billing is accurate.

Although it's not possible to add data to the User ID itself, you can consider setting a dynamic User state or store User metadata.

You should generate the User ID once per user or device, and reuse it for their lifetime. You can accomplish this by either passing the User ID to the client upon successful login or by persisting the User ID on the client where it can be retrieved the next time the PubNub instance is instantiated.

User Identification Confidentiality

Depending on your architecture and the security measures you take, the User ID may be visible to other clients, so we recommend you not use a username, email, or other potentially personally identifiable or confidential information. The User ID should be something that can be easily revoked and replaced, if necessary, without user interaction or even knowledge that it has happened.

Set the User ID

For your servers, the User ID value could be pulled from a server configuration file. For your clients, this value is received from your server after successful login.

JavaScript

<script type="text/javascript">
  var pubnub = new PubNub({
    publishKey: "myPublishKey",
    subscribeKey: "mySubscribeKey",
    userId: "myUniqueUserId"
});
<script>

Python

from pubnub.pnconfiguration import PNConfiguration
from pubnub.pubnub import PubNub

pnconfig = PNConfiguration()
pnconfig.publish_key = "myPublishKey"
pnconfig.subscribe_key = "mySubscribeKey"
pnconfig.user_id = "myUniqueUserId"

pubnub = PubNub(pnconfig)

Java

final UserId userId = new UserId("myUniqueUserId");
PNConfiguration pnConfig = new PNConfiguration(userId);
pnconfig.setPublishKey("myPublishKey");
pnconfig.setSubscribeKey("mySubscribeKey");

PubNub pubnub = PubNub.create(pnConfig);

Kotlin

val config = PNConfiguration(UserId("myUniqueUserId")).apply {
      publishKey = "myPublishKey"
      subscribeKey = "mySubscribeKey"
  }
  var pubnub = PubNub(config)

Go

pnconfig := pubnub.NewConfig()
pnconfig.SubscribeKey = "MySubscribeKey"
pnconfig.PublishKey = "MyPublishKey"
pnconfig.SetUserId(UserId("myUniqueUserId"))
pn := pubnub.NewPubNub(pnconfig)

C

pubnub_t *ctx = pubnub_alloc();
if (NULL == ctx) {
    puts("Couldn't allocate a Pubnub context");
    return -1;
}
pubnub_init(ctx, "MyPublishKey", "MySubscribeKey");
pubnub_set_user_id(ctx, "myUniqueUser_id");

Unity

using PubNubAPI;

PNConfiguration pnConfiguration = new PNConfiguration();
pnConfiguration.SubscribeKey = "my_subkey";
pnConfiguration.PublishKey = "my_pubkey";
pnConfiguration.UserId = "myUniqueUserId";
pubnub = new PubNub(pnConfiguration);

Swift

import PubNub

let config = PubNubConfiguration(
  publishKey: "demo",
  subscribeKey: "demo",
  userId: "myUniqueUserId"
)

let pubnub = PubNub(configuration: config)

Objective-C

#import <PubNub/PubNub.h>

PNConfiguration *pnconfig = [PNConfiguration configurationWithPublishKey:@"myPublishKey"
                                             subscribeKey:@"mySubscribeKey"];
pnconfig.uuid = "theClientUUID";
PubNub *pubnub = [PubNub clientWithConfiguration:pnconfig];

C#

using PubnubApi;

PNConfiguration pnConfiguration = new PNConfiguration();
pnConfiguration.SubscribeKey = "my_subkey";
pnConfiguration.PublishKey = "my_pubkey";
pnConfiguration.UserId = "myUniqueUserId";
pubnub = new PubNub(pnConfiguration);

Dart

final myKeyset = Keyset(
  subscribeKey: 'mySubscribeKey',
  publishKey: 'myPublishKey',
  userId: UserId('yourUniqueUserId')
  );

PHP

use PubNub\PNConfiguration;
use PubNub\PubNub;

$pnconf = new PNConfiguration();

$pnconf->setSubscribeKey("my-key");
$pnconf->setPublishKey("my-key");
$pnconf->setUserId("myUniqueUserId");
$pubnub = new PubNub($pnconf);

Ruby

pubnub = Pubnub.new(
    subscribe_key: :demo,
    publish_key:   :demo,
    user_id: 'myUniqueUserId'
)

Multiple Devices per User

Another design decision you may have to make is whether to allow a user to use your application on two or more devices at the same time. For example, a user might use chat on a browser, and then switch to a mobile device. Users can pass their device information as a dynamic state property if they wish to share it with other users in the application.

Users can connect from multiple devices, such as phones, tablets, desktops, etc., using the same User ID. Users can pass information about the device by using the Set State operation. The user’s dynamic state is persisted in memory for the time the user is connected to the application. This state is automatically cleared when the user disconnects from the application.

If a user is connected from multiple devices simultaneously, they will receive the same messages on each device. However, their presence online/offline status may be inaccurate if the user is connected via multiple devices.

Server generates User ID for the Client

Most often, you'll generate a User ID on your server, on behalf of a user, when the user registers in your application. The user's User ID is stored in your database along with other profile information for the user. You may want to reuse the user's User ID from your application to associate the user with PubNub.

When the user logs in to your application, you can pass the User ID back to the client application so it can be used during the PubNub object initialization.

Server generates User ID for its own use

If the server needs to interact with PubNub, each server instance should also set its User ID and reuse it when it instantiates the PubNub object. It's recommended that you include the User ID in your server's config file along with your PubNub API keys and other types of server config data.

User ID Impact

If you don't explicitly create and reuse a User ID for each user, it will negatively impact your application relative to PubNub's usage metrics, billing, and Presence features.

Billing

If your account is set up with the Monthly Active Users (MAU) pricing model, a user could end up having a new User ID created for them every time they sign in to your application. This results in a user being counted multiple times per month. For the sake of keeping your bill representative of your actual active user count, ensuring that each user has and uses their User ID with every use of your application is extremely important.

Presence

If you have enabled Presence for your keys, a user must be uniquely identifiable so that when that user joins a channel, you know which user that is. And if a user comes online, joins a channel, goes offline, then comes back online and joins that same channel with a different User ID, they will appear to be a different subscriber/user on that channel.

Server User ID Usage

Failure to reuse a User ID for your server instances can result in a dramatic increase in the monthly active user metrics because it might be that you're instantiating a new PubNub object every time a publish or grant operation is invoked. You can mitigate this by reusing the PubNub object rather than creating new instances (an instance pool pattern). Either way, proper User ID reuse is highly recommended on the server, and with each client.

Troubleshooting

Additionally, when you're troubleshooting your application, or PubNub Support is investigating an issue (whether it's Presence, billing, or something else), it's useful to be able to track a user through the system and from one request to another (in log searches) by User ID.