Set, get, and remove user metadata

Showing JavaScript examples.

Starting a new app? Use DataSync

DataSync is the successor to App Context. It does everything App Context does for users, channels, and memberships, and adds typed schemas, partial updates with ETags, field-level access control, and per-class expiry. Refer to How DataSync compares to App Context for a feature-by-feature comparison.

DataSync is currently available to new accounts and to accounts that are not actively using App Context. If your keysets already use App Context, keep using it for now. App Context remains fully supported and these pages stay accurate.

This guide shows you how to give a single user its App Context metadata: set its built-in and custom fields, read them back, and remove the whole record. App Context must be enabled on the keyset before you call it, and new keysets don't enable it by default. To read or list every user's metadata at once instead of one user, refer to Get metadata for all users.

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.

Set user metadata

Call Set UUID Metadata with a data object holding built-in fields such as name, email, externalId, and profileUrl, plus any custom fields your application needs. If you omit the User ID, the call applies to the client's own User ID. The call creates the record if it doesn't exist yet, or updates it if it does.

Unsupported partial updates of custom metadata

The value of the custom metadata parameter sent in this method always overwrites the value stored on PubNub servers. If you want to add new custom data to an existing one, you must:

1. Get the existing metadata and store it locally.
2. Append the new custom metadata to the existing one.
3. Set the entire updated custom object.

• JavaScript
• Java
• Kotlin
• C#
• Go
• Swift
• PHP
• Unity

1

If Access Manager is enabled on your keyset, this call requires an update permission grant on that User ID. On success, the call also fires the set App Context event other subscribers receive.

Pass the eTag from a get call as ifMatchesEtag on a set call to apply the update only if the record hasn't changed since you read it, so a mismatch returns HTTP 412. Most SDKs document this parameter on the same method as ifMatchesEtag. Check the API reference for your platform in Available SDKs for the exact name.

Get user metadata

Call Get UUID Metadata to read a user's current record. Most PubNub SDKs default to the client's own User ID when you omit one, though some expect you to pass it explicitly. Most also include the custom object in the response by default. Check your platform's API reference in Available SDKs to confirm.

• JavaScript
• Java
• Kotlin
• C#
• Go
• Swift
• PHP
• Unity

1

If Access Manager is enabled, this call requires a get permission grant on that User ID. A User ID with no metadata record yet returns a not-found error, since setting a userId on a client doesn't create one.

Remove user metadata

Call Remove UUID Metadata to delete a user's record entirely, including every custom field. There's no way to remove a single field without rewriting the record. Refer to Set user metadata to overwrite custom with everything except the field you want gone.

• JavaScript
• Java
• Kotlin
• C#
• Go
• Swift
• PHP
• Unity

1

If Access Manager is enabled, this call requires a delete permission grant on that User ID. Turning on Enforce referential integrity for memberships in the Admin Portal also deletes every membership pointing at this User ID when you remove its metadata. Leaving that setting off leaves those memberships in place, pointing at a User ID with no metadata record. Refer to Membership connects users and channels for the full referential-integrity behavior.

Set, get, and remove user metadata without code

BizOps Workspace's User Management module performs the same three operations from the Admin Portal, with no SDK call required:

• Create users. Set a new user's name, email, and custom fields.
• Update users. Change an existing user's fields.
• Delete users. Remove a user's metadata, including in bulk.

A record you create, edit, or delete in BizOps Workspace is the same record your SDK calls read and write. Changes in either place are immediately visible in the other.

Related tasks

• App Context. The three entity types and how App Context relates to messages and Presence.
• Get metadata for all users. Page through every user's metadata instead of one.
• Set, get, and remove memberships. Manage this user's channel list.
• App Context events. The set and delete event payload this operation produces.
• App Context API limits. Field-length limits for name, email, and custom.