User metadata

Users 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 display names, last online time, and user roles.

PubNub generates user metadata events when a user metadata is set or deleted.

Set user metadata

The setUUIDMetadata 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.

Note

If you update the custom property, you must completely replace the entire object; partial updates aren't supported.

Go to SDK

pubnub.objects.setUUIDMetadata({
    data: {
        uuid: 'john-doe',
        name: "John Doe",
        email: "johndoe@pubnub.com",
        custom: {
            "nickname": "jonny"
        }
    }
});

Go to SDK

Map<String, Object> custom = new HashMap<>();
custom.put("nickname", "jonny");
pubnub.setUUIDMetadata()
    .uuid("john-doe")
    .name("John Doe")
    .email("johndoe@pubnub.com")
    .custom(custom)
    .includeCustom(true)
    .async(new PNCallback<PNSetUUIDMetadataResult>() {
        @Override
        public void onResponse(@Nullable final PNSetUUIDMetadataResult result, @NotNull final PNStatus status) {
            if (status.isError()) {
                //handle error
            }
            else {
                //handle result
            }
        }
    });

Go to SDK

let johnDoe = PubNubUUIDMetadataBase(
  id: "john-doe", name: "John Doe",
  custom: ["title": "jonny"]
)

pubnub.set(user: johnDoe) { result in
  switch result {
  case let .success(uuidMetadata):
    print("The metadata for `\(uuidMetadata.metadataId)`: \(uuidMetadata)")
  case let .failure(error):
    print("Create request failed with error: \(error.localized### Description)")
  }
}

Go to SDK

self.client.objects().setUUIDMetadata()
    .uuid(@"john-doe")
    .name(@"John Doe")
    .custom(@{ @"nickname": @("jonny") })
    .email(@"johndoe@pubnub.com")
    .includeFields(PNUUIDCustomField)
    .performWithCompletion(^(PNSetUUIDMetadataStatus *status) {
        if (!status.isError) {
            /**
             * UUID metadata successfully has been set.
             * UUID metadata information available here: status.data.metadata
             */
        } else {
            /**
             * Handle UUID metadata set error. Check 'category' property to find out possible issue
             * because of which request did fail.
             *
             * Request can be resent using: [status retry]
             */
        }
    });

Go to SDK

pubnub.SetUUIDMetadata().Email("johndoe@pubnub.com").Name("John Doe").UUID("john-doe").Async((result, status) => {
    Debug.Log(result.Name);
    Debug.Log(result.Email);
    Debug.Log(result.ExternalID);
    Debug.Log(result.ProfileURL);
    Debug.Log(result.ID);
    Debug.Log(result.ETag);

});

Get user metadata

The getUUIDMetadata method retrieves metadata for the current user. On success, the PubNub SDK will return the all metadata of the user along with the status 200.

Go to SDK

pubnub.objects.getUUIDMetadata({
    uuid: 'john-doe',
});

Go to SDK

pubnub.getUUIDMetadata().async(new PNCallback<PNGetUUIDMetadataResult>() {
    @Override
    public void onResponse(@Nullable final PNGetUUIDMetadataResult result, @NotNull final PNStatus status) {
        if (status.isError()) {
            //handle error
        }
        else {
            //handle result
        }
    }
});

Go to SDK

pubnub.fetch(uuid: "john-doe") { result in
  switch result {
  case let .success(uuidMetadata):
    print("The metadata for `\(uuidMetadata.metadataId)`: \(uuidMetadata)")
  case let .failure(error):
    print("Fetch request failed with error: \(error.localized### Description)")
  }
}

Go to SDK

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

Go to SDK

pubnub.GetUUIDMetadata().UUID("john-doe").Async((result, status) =>
    {
        Debug.Log(result.Name);
        Debug.Log(result.Email);
        Debug.Log(result.ExternalID);
        Debug.Log(result.ProfileURL);
        Debug.Log(result.ID);
        Debug.Log(result.ETag);
    });

User events

User events are triggered when user metadata is set or deleted. Other users can receive these events by subscribing to the user's channel or if they are members of the same channel.

EventDescriptionPublish location
User Metadata SetUser metadata is set or updated.These events are published on {uuid} and {channel} memberships for the user.
User Metadata DeletedUser metadata is deleted.These events are published on {uuid} and {channel} memberships for the user.

User metadata set:

{
   "channel":"john-doe",
   "message":{
      "event":"set",
      "type":"uuid",
      "data":{
         "id":"john-doe",
         "name":"John Doe",
         "email":"johndoe@pubnub.com",
         "updated":"2020-06-10T16:22:11.035374Z",
         "eTag":"AY39mJKK//C0VA"
      }
   },
   "subscription":null,
   "timetoken":"15119446002445794"
}

User metadata removed:

{
   "channel":"john-doe",
   "message":{
      "event":"deleted",
      "type":"uuid",
      "data":{
         "id":"john-doe",
         "name":"John Doe",
         "email":"johndoe@pubnub.com",
         "updated":"2020-06-10T16:22:11.035374Z",
         "eTag":"AY39mJKK//C0VA"
      }
   },
   "subscription":null,
   "timetoken":"15119446002445794"
}

Refer to User Metadata to learn more about working with user metadata.

←SetupPermissions→