how_to_understand_userid_uuid.md•4.88 kB
# Understanding PubNub `userId` (Formerly UUID)
In PubNub, a `userId` (historically referred to as `UUID` - Universally Unique Identifier) is a crucial string identifier that represents a client connecting to the PubNub network. This client could be an end-user, a device (like an IoT sensor), or a server process.
## Purpose of `userId`
The `userId` serves several important functions:
1. **Client Identification:** It uniquely identifies a specific instance of a PubNub client.
2. **Presence:** If PubNub's Presence feature is enabled, the `userId` is used to:
* Announce when a user joins or leaves a channel.
* Track which users are currently subscribed to a channel (`hereNow` API).
* Allow users to set and get presence state information.
A consistent `userId` is vital for Presence to work correctly. If a client reconnects with a different `userId`, Presence will see it as a new user joining and an old user leaving.
3. **Message Persistence (History):** When messages are retrieved from history, the `userId` of the publisher is often included in the message envelope, allowing recipients to know who sent the message.
4. **App Context (Objects):** PubNub's App Context feature allows you to store metadata about users (UUIDs), channels, and memberships. The `userId` is the key for user metadata.
5. **Access Manager (PAM):** Permissions can be granted to specific `userId`s, allowing fine-grained access control.
6. **Billing and Analytics:** Usage metrics are often aggregated or can be filtered based on `userId`s, helping you understand how different users or devices interact with your PubNub application.
## `userId` Requirements and Best Practices
* **Required Parameter:** In modern PubNub SDKs (typically v4 and later for JavaScript, and corresponding versions for other languages), providing a `userId` during the PubNub client object instantiation is **mandatory**.
* If not provided, the SDK will usually throw an error or refuse to initialize.
* Older SDK versions might have auto-generated a random `userId` if one wasn't supplied. This practice led to issues with Presence consistency and analytics, hence the change to make it a required parameter.
* **Uniqueness:** While not strictly enforced by PubNub to be globally unique across all PubNub customers, it should be unique within the context of *your application* for each distinct user or device. Using standard UUID formats (e.g., UUIDv4) is a good way to ensure this, but any unique string is acceptable.
* **Length:** Up to 64 characters.
* **Persistence:** For a given end-user or device, the **`userId` should be persisted and reused** across sessions and application restarts.
* **How to Persist:**
* **User Authentication:** After a user logs into your application via your backend, your server can provide the client with its assigned persistent `userId`.
* **Local Storage:** The client application can store the `userId` in local storage (e.g., browser localStorage, mobile device's persistent storage) and retrieve it the next time the PubNub instance is created.
* **Device ID:** For IoT devices, a hardware ID or a provisioned unique identifier can be used.
* **Consistency is Key:** Using a consistent `userId` is critical for features like Presence. If a user disconnects and reconnects with a *new* `userId`, PubNub will see it as a different user.
## Setting the `userId`
The method for setting the `userId` depends on the PubNub SDK you are using.
**1. During PubNub Instance Initialization (Recommended):**
This is the most common and preferred way.
**JavaScript SDK Example:**
```javascript
var myPersistedUserId = "user_alice_12345"; // Retrieved from auth system or local storage
var pubnub = new PubNub({
subscribeKey: "YOUR_SUBSCRIBE_KEY",
publishKey: "YOUR_PUBLISH_KEY",
userId: myPersistedUserId // Set the userId here
});
```
**2. Using a Setter Method (If Available):**
Some SDKs might provide a method to set or change the `userId` after initialization, though initializing with it is generally better.
**JavaScript SDK Example:**
```javascript
// var pubnub = new PubNub({ /* ... config without userId initially if SDK allows ...
## Transition from `UUID` to `userId`
The term `UUID` was used in older PubNub documentation and SDKs. The functionality is the same, but `userId` is the more current and descriptive term. If you are working with older code or documentation, `uuid` and `userId` (when referring to the client identifier) can often be considered interchangeable in concept, but modern SDKs will expect the parameter to be named `userId`.
If you have any questions about `userId` configuration or behavior with your specific SDK version, contact PubNub Support at [support@pubnub.com](mailto:support@pubnub.com).