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.

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

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

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

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.

JavaScript

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

Java

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(result -> { /* check result */ });

Swift

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

pubnub.setUserMetadata(johnDoe) { result in
  switch result {
  case let .success(userMetadata):
    print("The metadata for `\(userMetadata.metadataId)`: \(userMetadata)")
  case let .failure(error):
    print("Create request failed with error: \(error.localizedDescription)")
  }
}

Objective-C

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

show all 21 lines

Unity

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.

JavaScript

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

Java

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

Swift

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)")
  }
}

Objective-C

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]

show all 18 lines

Unity

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.

Event	Description	Publish location
User Metadata Set	User metadata is set or updated.	These events are published on {uuid} and {channel} memberships for the user.
User Metadata Deleted	User 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"

show all 16 lines

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"

show all 16 lines