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.
|Yes||The user's unique identifier. It must not be empty, and may contain up to 36 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 and objects aren't supported.|
Setting user metadata
This method stores user metadata in PubNub and optionally includes custom data.
Getting a user's metadata
This method returns the specified user object, optionally including the user's custom data object.
Getting metadata for all users
getUsers() method (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:
Updating a user's metadata
You can use the
update method to update properties for a 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 Subscribing to a user's events for more details.
You can update all the user object's properties except the
id. If you update the
custom property, you must completely replace the entire object; partial updates aren't supported.
Deleting a user's metadata
deleteUser() method deletes the specified user object.
PubNub generates a "User Deleted" event when a user is deleted. You can subscribe to the user inbox channel to receive these events. Refer to Subscribing to a user's events for more details.
Subscribing to a user's 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 channel. These events can be enabled or disabled from your key settings in the PubNub Dashboard.
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.
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.
Using state-change events
PubNub also triggers presence
state-change events anytime the user's state is changed using the state API. Clients can receive these events directly by subscribing to presence channels to keep a user's state up to date.
Refer to the Presence events section to learn more about presence events.