Add custom metadata

In PubNub, you can add descriptive metadata to channels, users, and the relationships between them.

There are three items you can assign metadata to: users, channels, and memberships. Unlike dynamic state, metadata is stored in PubNub and is available anytime. Let's look at each of them.

Metadata scope by entity:

Entity Type	Metadata Scope	Use Cases
Channels	Channel-wide	Topic categorization, display name, description
Users	User profile	Preferences, roles, profile fields
Memberships	Relationship	Permission levels, user-channel settings

Users have four predefined metadata properties: name, email, profileURL, and externalId. There is also a custom property that allows you to store any attribute.

The code below adds a name, an e-mail, and a custom nickname properties to provide more information about a user.

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.

JavaScript

pubnub.objects.setUUIDMetadata({
    data: {
        name: "Thomas Anderson",
        email: "t.anderson@pubnub.com",
        custom: {
            "nickname": "The One"
        }
    }
});

Swift

let userMetadata = PubNubUserMetadataBase(
  metadataId: "uuid",
  name: "Thomas Anderson",
  email: "t.anderson@pubnub.com",
  custom: [ "nickname": "The One" ]
)

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

Objective-C

self.client.objects().setUUIDMetadata()
    .uuid(@"uuid")
    .name(@"Thomas Anderson")
    .custom(@{ @"nickname": @("The One") })
    .email(@"t.anderson@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

Android

Map<String, Object> custom = new HashMap<>();
custom.put("nickname", "The One");
pubnub.setUUIDMetadata()
    .name("Thomas Anderson")
    .email("t.anderson@pubnub.com")
    .custom(custom)
    .includeCustom(true)
    .async(result -> { /* check result */ });

C#

PNResult<PNSetUuidMetadataResult> setUuidMetadataResponse = await pubnub.SetUuidMetadata()
        .Uuid(config.Uuid)
        .Name("Thomas Anderson")
        .Email("t.anderson@pubnub.com")
        .Custom(new Dictionary<string, object>() { { "nickname", "The One" } })
        .ExecuteAsync();
PNSetUuidMetadataResult setUuidMetadataResult = setUuidMetadataResponse.Result;
PNStatus status = setUuidMetadataResponse.Status;

Python

pubnub.set_uuid_metadata().uuid(this_uuid) \
    .set_name("Thomas Anderson") \
    .email("t.anderson@pubnub.com") \
    .custom({"nickname": "The One"}) \
    .include_custom(True) \
    .sync()

Dart

var uuidMetadataInput = UuidMetadataInput(
      name: 'Thomas Anderson',
      email: 't.anderson@pubnub.com',
      custom: {'nickname': 'The One'});
  var result = await pubnub.objects.setUUIDMetadata(uuidMetadataInput);

Kotlin

pubnub.setUUIDMetadata(
    uuid = "unique uuid",
    includeCustom = true,
    name = "Thomas Anderson",
    email = "t.anderson@pubnub.com",
    custom = "nickname = The One",
).async { result, status ->
            if (status.error) {
                //handle error
            } else if (result != null) {
                //handle result
            }
        }

Channels have two predefined metadata properties: name and description. The custom property allows you to store any attribute.

The code below adds all three properties to provide more information about a channel. This way you're keeping all channel information in one place and can easily present additional data in your app's user interface.

JavaScript

pubnub.objects.setChannelMetadata({
    channel: "chats_guilds.mages_guild",
    data: {
      name: "Mages guild",
      description: "Mages guild official chatroom.",
      custom: { "administrator": "thomas_anderson" }
    }
});

Swift

let channelMetadata = PubNubChannelMetadataBase(
  metadataId: "chats_guilds.mages_guild",
  name: "Mages guild",
  channelDescription: "Mages guild official chatroom.",
  custom: [ "administrator": "thomas_anderson" ]
)


pubnub.set(channel: channelMetadata) { result in
  switch result {
  case let .success(metadata):
    print("The metadata for `\(metadata.metadataId)`: \(metadata)")
  case let .failure(error):
    print("Request failed with error: \(error.localizedDescription)")
  }

show all 16 lines

Objective-C

self.client.objects().setChannelMetadata(@"chats_guilds.mages_guild")
    .name(@"Mages guild")
    .information(@"Mages guild official chatroom.")
    .custom(@{ @"administrator": @"thomas_anderson" })
    .includeFields(PNChannelCustomField)
    .performWithCompletion(^(PNSetChannelMetadataStatus *status) {
      if (!status.isError) {
          /**
           * Channel metadata successfully has been set.
           * Channel metadata information available here: status.data.metadata
           */
      } else {
          /**
           * Handle channel metadata update error. Check 'category' property to find out possible
           * issue because of which request did fail.

show all 20 lines

Java

Map<String, Object> custom = new HashMap<>();
custom.put("administrator", "thomas_anderson");
pubnub.setChannelMetadata()
    .channel("chats_guilds.mages_guild")
    .name("Mages guild")
    .description("Mages guild official chatroom.")
    .custom(custom)
    .includeCustom(true)
    .async(result -> { /* check result */ });

C#

PNResult<PNSetChannelMetadataResult> setChannelMetadataResponse = await pubnub.SetChannelMetadata()
    .Channel("chats_guilds.mages_guild")
    .Name("Mages guild")
    .Description("Mages guild official chatroom.")
    .Custom(new Dictionary<string, object>() { { "administrator", "thomas_anderson" } })
    .IncludeCustom(true)
    .ExecuteAsync();
PNSetChannelMetadataResult setChannelMetadataResult = setChannelMetadataResponse.Result;
PNStatus status = setChannelMetadataResponse.Status;

Python

pubnub.set_channel_metadata().channel("chats_guilds.mages_guild") \
    .set_name("Mages guild") \
    .description("Mages guild official chatroom.") \
    .custom({"administrator": "thomas_anderson" }) \
    .include_custom(True) \
    .sync()

Dart

var channelMetadataInput = ChannelMetadataInput(
    name: 'chats_guilds.mages_guild', description: 'Mages guild official chatroom.', custom: { 'administrator': 'thomas_anderson'});

var result = await pubnub.objects
    .setChannelMetadata('my_channel', channelMetadataInput);

Kotlin

pubnub.setChannelMetadata(
    channel = "chats_guilds.mages_guild",
    includeCustom = true,
    description = "Mages guild official chatroom",
    custom = "administrator thomas_anderson"
).async { result, status ->
            if (status.error) {
                //handle error
            } else if (result != null) {
                //handle result
            }
        }

Memberships are relationships between users and channels. Use membership metadata to display a user’s channel list or to store user‑channel settings.

Memberships have no predefined metadata properties, as the membership relation is metadata in itself.

The code below adds the current user to the chats_guilds.mages_guild and chats_inbox.user_1905 channels and adds the friendlist metadata to the newly created chats_inbox.user_1905 membership.

JavaScript

pubnub.objects.setMemberships({
    channels: [
        "chats_guilds.mages_guild",
    {id: "chats_inbox.user_1905", custom: {friendlist: true}
    }]
});

Swift

let channels = [
  PubNubMembershipMetadataBase(userMetadataId: "uuid", channelMetadataId: "chats_guilds.mages_guild"),
  PubNubMembershipMetadataBase(userMetadataId: "uuid", channelMetadataId: "chats_inbox.user_1905", custom: [ "friendlist": true ]),
]

pubnub.setMemberships(uuid: "uuid", channels: channels) { result in
  switch result {
  case let .success((memberships, _)):
    print("Memberships: \(metadata)")
  case let .failure(error):
    print("Request failed with error: \(error.localizedDescription)")
  }
}

Objective-C

NSArray<NSDictionary *> *channels = @[
  @{ @"channel": @"chats_guilds.mages_guild" },
  @{ @"channel": @"chats_inbox.user_1905", @"custom": @{ @"friendlist": @YES } }
];

self.client.objects().setMemberships()
    .uuid(@"uuid")
    .channels(channels)
    .includeCount(YES)
    .limit(40)
    .includeFields(NMembershipCustomField | PNMembershipChannelField)
    .performWithCompletion(^(PNManageMembershipsStatus *status) {
        if (!status.isError) {
            /**
             * UUID's memberships successfully set.

show all 30 lines

Android

Map<String, Object> custom = new HashMap<>();
custom.put("friendlist", true);
pubnub.setMemberships()
    .channelMemberships(Arrays.asList(PNChannelMembership.channel("chats_guilds.mages_guild"), PNChannelMembership.channelWithCustom("chats_inbox.user_1905", custom)))
    .async(result -> { /* check result */ });

C#

List<PNMembership> setMembershipChannelMetadataIdList = new List<PNMembership>();
if (!string.IsNullOrEmpty(seMembershipChannelMetaId))
{
    setMembershipChannelMetadataIdList.Add(new PNMembership() { Channel = "chats_guilds.mages_guild" });
    setMembershipChannelMetadataIdList.Add(new PNMembership() { Channel = "chats_inbox.user_1905", Custom = new Dictionary<string, object>() { { "friendlist", true } } });
}

PNResult<PNMembershipsResult> setMembershipsResponse = await pubnub.SetMemberships()
    .Uuid("my-uuid")
    .Channels(setMembershipChannelMetadataIdList)
    .Include(new PNMembershipField[] { PNMembershipField.CUSTOM, PNMembershipField.CHANNEL, PNMembershipField.CHANNEL_CUSTOM })
    .IncludeCount(true)
    .ExecuteAsync();
PNMembershipsResult setMembershipsResult = setMembershipsResponse.Result;
PNStatus status = setMembershipsResponse.Status;

Python

pubnub.set_memberships().uuid(this_uuid).channel_memberships([
        PNChannelMembership.channel("chats_guilds.mages_guild"),
        PNChannelMembership.channel_with_custom("chats_inbox.user_1905", {"friendlist": True})
    ])
    .include_custom(True)
    .sync()

Dart

var setMetadata = [
  MembershipMetadataInput('chats_inbox.user_1905', custom: {'friendlist': 'true'}),
  MembershipMetadataInput('chats_guilds.mages_guild ')
];

var result = await pubnub.objects
    .setMemberships(setMetadata, includeChannelFields: true);

Kotlin

val custom: MutableMap<String, Any> = HashMap()
custom["friendlist"] = true

pubnub.setMemberships(listOf(
    PNChannelWithCustom(channel = "chats_guilds.mages_guild"),
    PNChannelWithCustom(channel = "chats_inbox.user_1905", custom = custom))
).async { result, status ->
        if (status.error) {
            //handle error
        } else if (result != null) {
            //handle result
        }
    }

To manage visibility and permissions, use Access Manager (see Manage access).