All chat applications have a notion of a user. It's important to be able to uniquely identify users as they interact with the PubNub Network. Usually, a user is a human end user — a person using an app to interact with a system (via a laptop, phone, tablet, or kiosk).
You use a
uuid to uniquely identify each user on the system. Users can connect from multiple devices, such as phones, tablets, desktops, etc., using the same
uuid. If a user is connected from multiple devices simultaneously, they will receive the same messages on each device.
Use this method to initialize the PubNub Client API context and establish account-level credentials such as publish and subscribe keys. You can create a free account and get your keys from the PubNub Dashboard.
Each client should pass a
uuid that represents the user when it connects to PubNub. The
uuid is necessary to ensure that your billing is accurate, and for other features like presence and storage to work as expected. A
uuid is a string with a maximum length of 64 characters.
Secret keys should be server-only
You can initialize PubNub from a server with the
secretKey to get root permissions for the Access Manager. With this feature you don't have to grant access to individual PubNub resources for your server.
For security reasons, you should only include the
secretKey on a well-secured server. The secret key is only required if the server needs root permissions to PubNub Access Manager to manage permissions for clients.
Managing user metadata
Clients can optionally store metadata such as a name, profile URL, external ID, and email address. You can also use a custom field to store additional data for a user. The metadata can be fetched by other users and persists in the database until it's explicitly removed. Some examples of custom data are nicknames, last online time, and user roles.
|No||The user's name. If specified, 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.|
Setting user metadata
This method stores user metadata in PubNub. You can use it to add new or update existing metadata properties. The method returns the updated user metadata, including the user's custom data.
PubNub generates a "User Metadata Set" event when a user metadata is set. Refer to Objects Events for details on receiving these events.
If you update the
custom property, you must completely replace the entire object; partial updates aren't supported.
Getting user metadata
This method returns metadata for the specified user, including the user's custom data.
Getting metadata for all users
This method returns a paginated list of metadata objects for users, optionally including custom data objects. The example below retrieves all users in our database, including their custom data fields:
Removing user metadata
This method removes the specified user's metadata.
PubNub generates a "User Metadata Deleted" event when user metadata is removed. Refer to Objects Events for details on receiving these events.
Managing dynamic user state
Users can set dynamic custom state on one or more channels. This custom state persists on a channel as long as the user stays subscribed to that channel. Some examples of custom state are to add your score, game state, or location in an application if it changes frequently.
PubNub triggers presence
state-change events anytime the user's state is modified. Clients can receive these events by subscribing to presence channels. Refer to Presence events for more details.
Setting user state
This method sets dynamic state for a user on channels. 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 channel.
Getting user state
This method retrieves a user's state information.