Users & Devices

All clients have a notion of a user, a device, or both. Uniquely identifying either is an important concept with respect to 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 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.

UUID Usage

A UUID (Universally Unique Identifier) is a unique string of up to 64 characters used to identify a client (end user, device, or server) that connects to the PubNub platform. The UUID is required to establish a connection to PubNub and to ensure your billing is accurate.

UUIDs are also important for other features like presence and storage to work as expected. You should generate the UUID once per user or device, and you should reuse it for their lifetime.

It's mandatory to pass a UUID when you instantiate a PubNub instance (new PubNub()). This UUID should remain unchanged for the lifetime of the user or the device that connects to PubNub. You can accomplish this by either passing the UUID to the client upon successful login or by persisting the UUID 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 UUID may be visible to other clients, so we recommend you not use a username, email, or other potentially personally identifiable or confidential information. The UUID should be something that can be easily revoked and replaced, if necessary, without user interaction or even knowledge that it has happened.

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 UUID. 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, it's possible that their presence online/offline status is inaccurate if the user is connected via multiple devices.

Server generates UUID for the Client

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

When the user logs in to your application, you can pass that user's UUID back to the client application so it can be used during the PubNub object initialization.

Server generates UUID for its own use

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

Setting the UUID

In the following code examples, uuid is used as a placeholder variable that would hold the value. For your servers, this value would be pulled from a server config file. For your clients, this value is received from your server after successful login.

var pubnub = new PubNub({
subscribeKey: "mySubscribeKey",
publishKey: "myPublishKey",
uuid: uuid

UUID Impact

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


If your account is set up with the Monthly Active Users (MAU) pricing model, a user could end up having a new UUID 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 own UUID with every use of your application is extremely important.


If you have enabled Presence for your keys, it's important that a user is 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 UUID, they will appear to be a different subscriber/user on that channel.

Server UUID Usage

Failure to reuse a UUID 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 UUID reuse is highly recommended on the server, and with each client.


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 UUID.