Users & Devices

All clients have a notion of a user, a device, or both. Uniquely identifying each one is essential for how they interact with the PubNub platform. Clients are entities that connect through your app. In most apps, users are people who connect from the app.

The relationship between users and devices matters. One user can use your app on multiple devices. Decide whether your app allows simultaneous multi‑device use. That choice determines how you identify users and 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 92 characters used to identify a single client (end user, device, or server) that connects to PubNub. User IDs are also important for features like Presence and Message Persistence.

User ID is required

Set the User ID to connect to PubNub and ensure accurate billing.

User IDs are kept lean by design. Use User metadata or dynamic User state (temporary while connected) for additional data.

Generate the User ID once per user or device. Reuse it for their lifetime. Pass it to the client after login, or persist it so the next PubNub instance can reuse it. In SDKs, parameter names such as userId, user_id, and uuid refer to the same User ID value.

User Identification Confidentiality

The User ID may be visible to other clients. Don't use usernames, emails, or other personally identifiable or confidential information. Choose a value you can revoke and replace without user action.

Device-level presence tracking

Multiple devices that share the same User ID count as one user for billing. If one device unsubscribes while others stay subscribed, Presence can emit a leave event followed by a join event.

To address this, consider:

• Assign a different identifier to each device.
• Unsubscribe from channels only if no other devices stay subscribed.
• If disconnects without unsubscribe are acceptable, rely on the timeout presence event instead.

Set the user ID

For servers, read the User ID from a server config file. For clients, receive the User ID from your server after 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

PNConfiguration.Builder configBuilder = PNConfiguration.builder(new UserId("yourUserId"), "yourSubscribeKey");
// publishKey from Admin Portal (only required if publishing)
configBuilder.publishKey("PublishKey");
PubNub pubNub = PubNub.create(configBuilder.build());

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 PubNubSDK

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

Decide whether a user can use your app on two or more devices at the same time. For example, a user might use chat in a browser and then switch to a phone. Users can pass device information as dynamic state if they want to share it with others in the app.

Users can connect from multiple devices using the same User ID. They can pass device info with the Set State operation. Dynamic state is kept in memory while connected and clears on disconnect.

If a user connects from multiple devices at once, they receive the same messages on each device. Presence status may be inaccurate in this case.

Server generates user ID for the client

Most often, you generate a User ID on your server when the user registers. Store it with the user’s profile. Reuse it to associate the user with PubNub.

When the user logs in, pass the User ID to the client. Use it during PubNub initialization.

Server generates user ID for its own use

If the server interacts with PubNub, each server instance should set and reuse its User ID. Include the User ID in your server config with your PubNub API keys.

User ID impact

Reuse a User ID for each user to optimize usage metrics, billing, and Presence.

Billing

If you use the Monthly Active Users (MAU) pricing model, creating a new User ID on each sign‑in can count the same user multiple times in a month. Reuse the same User ID to keep billing accurate.

Presence

With Presence enabled, a user must be uniquely identifiable. If a user rejoins a channel with a different User ID, they appear as a different subscriber on that channel.

Server user ID usage

If you don’t reuse a User ID for server instances, monthly active user metrics can increase, especially if you create a new PubNub object for each call. Reuse the PubNub object where possible (an instance pool pattern). Always reuse the User ID on servers and clients.

Troubleshooting

When you troubleshoot your app or PubNub Support investigates an issue, tracking a user by User ID across requests and logs is useful.