Users are entities who connect to the PubNub platform via mobile or web applications. Users are identified by a unique ID and have properties such as a name, profile URL, external ID, and email address. They can have additional properties that are stored as custom fields.
You don't need to create users to perform operations from a client application. Users only need to be created if you need to store user attributes and memberships inside PubNub.
|Yes||The user's unique identifier. It must not be empty, and may contain up to 92 characters.|
|Yes||The user's name. The name must not be empty or consist only of whitespace characters and can be a maximum of 200 characters.|
|No||The user's email address. Maximum 80 characters.|
|No||The user's external identifier.|
|No||The URL of the user's profile picture.|
|No||JSON object of key-value pairs with supported data types. Values must be scalar only; arrays or objects are not supported.|
Initialize PubNub with a user
Use this method to initialize the PubNub Client API context and establish account-level credentials such as publish and subscribe keys. You can create an account and get your keys from the PubNub Dashboard.
It's important to call this function before you attempt to use any API functionality.
Each client should pass a
uuid that represents the user when it connects to PubNub. If a user is signed into multiple clients, each client should use the same UUID. The UUID is needed to ensure that your billing is accurate, and for other features like presence and storage to work as expected.
Create a user
User creation is a server-side operation. Refer to Create and Manage Users for details.
Get my user
This operation returns the specified user object and optionally includes the user's custom data object.
Get all users
getUsers() operation (in Swift, it's
fetchUsers()) returns a paginated list of user objects and optionally includes each user's custom data object.
In this example, we retrieve all users in our database, including their custom data fields:
Update my user
You can use the
update method to update properties for your user. Returns the updated user object, optionally including the user's custom data object.
A "User Updated" event is generated when user properties are updated. You can subscribe to the user inbox channel to receive these events. Refer to User Events for more details.
You can update all the user object's properties, except for the
id. If you update the custom property, you must completely replace the entire custom object; partial updates aren't supported.
Delete a user
User deletion is a server-side operation. Refer to Create and Manage Users for details.
Subscribe to my user events
You can subscribe to your user's inbox to receive events that are specific for the user, like alerts or game updates. Your application should wait for a
PNConnectedCategory status event to confirm that the subscription is successful.
You can also use the user inbox to receive events when the user record is updated, or when the user is added or removed from a space. These events can be enabled or disabled from your key settings in the PubNub Dashboard.
Refer to event listeners to learn more about how to set event listeners for events.
Working with user state
Use the state API to set/get key/value pairs specific to a subscriber UUID.
The set-state and get-state methods work with user state information.
The state is an object of key/value pairs with any arbitrary data, as long as the data is of type
string. When you set or update the state, PubNub fires a state-change event to other users on the space.
PubNub stores the state for the time the user is online.
Setting dynamic state for a user
This operation sets extra information for a user on a space.
Getting dynamic state for a user
This operation retrieves a user's state information.