User Metadata

Manage user data with BizOps Workspace

You can create, edit, or delete users and their data using BizOps Workspace on Admin Portal that provides a preview of all users available on your apps' keysets.

The App Context feature provides easy-to-use, serverless storage for user metadata, channel metadata, channel memberships, and channel members without the need to stand up an external infrastructure.

Clients can optionally store metadata for users to use them in front-end applications and enhance your application. You can store any of the predefined properties for a user such as name, email, profileURL, externalId. Additionally, you can use a custom property to store any custom attribute for a user. Some examples of custom data are nickname, color etc.

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.

PubNub also generates events when the metadata associated to a particular user is set or deleted. Your application can receive these events in real time and dynamically react to data changes within the app. You can enable these events from the Admin Portal.

Events for each user are published to a channel named for each user. For example, to receive events for the user with User ID chat-user-9A7X8, you would subscribe to the channel named chat-user-9A7X8.

Illuminate & sensitive data

You can capture and track your App Context data in Illuminate for real-time decisioning and analytics. Illuminate captures all data you define with JSON paths and map when creating measures and dimensions for the Business Objects. For this reason, make sure you don’t include any PII data (e-mail address, profile URL, or IP address) in the custom fields of your App Context mappings.

Set user metadata

You can set any of the predefined or custom user metadata by providing the desired information as key/value pairs.

API limits

To learn about the maximum length of parameters used to set user metadata, refer to REST API docs.

The code below adds the name, email, and custom nickname information to the current user.

JavaScript

pubnub.objects.setUUIDMetadata({
    data: {
        name: "John Doe",
        email: "johndoe@pubnub.com",
        custom: {
            "nickname": "Mr. Mysterious"
        }
    }
});

Objective-C

self.client.objects().setUUIDMetadata()
    .uuid(@"uuid")
    .name(@"John Doe")
    .custom(@{ @"nickname": @("Mr. Mysterious") })
    .email(@"johndoe@pubnub.com")
    .includeFields(PNUUIDCustomField)
    .performWithCompletion(^(PNSetUUIDMetadataStatus *status) {
        if (!status.isError) {
            /**
             * User ID metadata successfully has been set.
             * User ID metadata information available here: status.data.metadata
             */
        } else {
            /**
             * Handle User ID metadata set error. Check 'category' property to find out possible issue

show all 21 lines

Java

Map<String, Object> custom = new HashMap<>();
custom.put("nickname", "Mr. Mysterious");
pubnub.setUUIDMetadata()
    .name("John Doe")
    .email("johndoe@pubnub.com")
    .custom(custom)
    .includeCustom(true)
    .async(result -> { /* check result */ });

C#

PNResult<PNSetUuidMetadataResult> setUuidMetadataResponse = await pubnub.SetUuidMetadata()
        .Uuid(config.Uuid)
        .Name("John Doe")
        .Email("johndoe@pubnub.com")
        .Custom(new Dictionary<string, object>() { { "nickname", "Mr. Mysterious" } })
        .ExecuteAsync();
PNSetUuidMetadataResult setUuidMetadataResult = setUuidMetadataResponse.Result;
PNStatus status = setUuidMetadataResponse.Status;

On success, the PubNub SDK will return the metadata of the user along with the status 200. It will also fire a User Metadata Set event that can be consumed by other clients. Refer to the Receive Messages section to learn more.

Get user metadata

You can retrieve the metadata of the current user. The code below returns all metadata for the current user.

JavaScript

pubnub.objects.getUUIDMetadata();

Objective-C

self.client.objects().uuidMetadata()
    .uuid(@"uuid")
    .includeFields(PNUUIDCustomField)
    .performWithCompletion(^(PNFetchUUIDMetadataResult *result, PNErrorStatus *status) {
      if (!status.isError) {
          /**
           * User ID metadata successfully fetched.
           * Fetched User ID metadata information available here: result.data.metadata
           */
      } else {
          /**
           * Handle User ID metadata fetch error. Check 'category' property to find out possible issue
           * because of which request did fail.
           *
           * Request can be resent using: [status retry]

show all 18 lines

Java

pubnub.getUUIDMetadata().async(result -> { /* check result */ });

C#

// Get Metadata for the current user
PNResult<PNGetUuidMetadataResult> getUuidMetadataResponse = await pubnub.GetUuidMetadata()
    .ExecuteAsync();
PNGetUuidMetadataResult getUuidMetadataResult = getUuidMetadataResponse.Result;
PNStatus status = getUuidMetadataResponse.Status;


// Get Metadata for a specific user
PNResult<PNGetUuidMetadataResult> getUuidMetadataResponse = await pubnub.GetUuidMetadata()
    .Uuid("my-uuid")
    .ExecuteAsync();
PNGetUuidMetadataResult getUuidMetadataResult = getUuidMetadataResponse.Result;
PNStatus status = getUuidMetadataResponse.Status;

On success, the PubNub SDK will return the all metadata of the user along with the status 200.

Get metadata for all users

You can also retrieve metadata for all users at once. If you're interested in their custom metadata as well, you can optionally specify whether custom metadata should be included in the response. The code below returns all predefined and custom metadata of all users:

JavaScript

pubnub.objects.getAllUUIDMetadata();

Objective-C

self.client.objects().allUUIDMetadata()
    .start(@"<next from previous request>")
    .includeFields(PNUUIDCustomField)
    .performWithCompletion(^(PNFetchAllUUIDMetadataResult *result, PNErrorStatus *status) {
        if (!status.isError) {
            /**
             * UUID metadata successfully fetched.
             * Result object has following information:
             *   result.data.metadata - List of fetched UUID metadata.
             *   result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
             *   result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
             *   result.data.totalCount - Total number of created UUID metadata.
             */
        } else {
            /**

show all 22 lines

Java

pubnub.getAllUUIDMetadata()
    .includeTotalCount(true)
    .includeCustom(true)
    .async(result -> { /* check result */ });

C#

PNResult<PNGetAllUuidMetadataResult> getAllUuidMetadataResponse = await pubnub.GetAllUuidMetadata()
    .IncludeCustom(true)
    .IncludeCount(true)
    .ExecuteAsync();
PNGetAllUuidMetadataResult getAllUuidMetadataResult = getAllUuidMetadataResponse.Result;
PNStatus status = getAllUuidMetadataResponse.Status;

On success, the PubNub SDK will return the all metadata of all users associated with the API key along with the status 200.

Remove user metadata

You can remove all metadata for a single user. The code below removes all metadata of the current user.

Cascading deletes

Enabling referential integrity on your app’s keyset in the Admin Portal ensures that deleting a user entity automatically deletes any memberships related to this user. If it's not enabled, deleting a user does not automatically delete any associated membership objects.

JavaScript

pubnub.objects.removeUUIDMetadata();

Objective-C

self.client.objects().removeUUIDMetadata()
    .uuid(@"uuid")
    .performWithCompletion(^(PNAcknowledgmentStatus *status) {
        if (!status.isError) {
             // User successfully deleted.
        } else {
            /**
             * Handle user delete error. Check 'category' property to find out possible issue
             * because of which request did fail.
             *
             * Request can be resent using: [status retry]
             */
        }
    });

Java

pubnub.removeUUIDMetadata()
    .async(result -> { /* check result */ });

C#

PNResult<PNRemoveUuidMetadataResult> removeUuidMetadataResponse = await pubnub.RemoveUuidMetadata()
    .ExecuteAsync();
PNRemoveUuidMetadataResult removeUuidMetadataResult = removeUuidMetadataResponse.Result;
PNStatus status = removeUuidMetadataResponse.Status;

On completion, the PubNub SDK will fire object -> uuid -> delete event that can be consumed by other clients. Refer to the Receive Messages document to learn more.