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

1pubnub.objects.setUUIDMetadata({
2    data: {
3        name: "Thomas Anderson",
4        email: "t.anderson@pubnub.com",
5        custom: {
6            "nickname": "The One"
7        }
8    }
9});

Swift

1let userMetadata = PubNubUserMetadataBase(
2  metadataId: "uuid",
3  name: "Thomas Anderson",
4  email: "t.anderson@pubnub.com",
5  custom: [ "nickname": "The One" ]
6)
7

8pubnub.setUserMetadata(userMetadata) { result in
9  switch result {
10  case let .success(metadata):
11    print("The metadata for `\(metadata.metadataId)`: \(metadata)")
12  case let .failure(error):
13    print("Request failed with error: \(error.localizedDescription)")
14  }
15}

Objective-C

1self.client.objects().setUUIDMetadata()
2    .uuid(@"uuid")
3    .name(@"Thomas Anderson")
4    .custom(@{ @"nickname": @("The One") })
5    .email(@"t.anderson@pubnub.com")
6    .includeFields(PNUUIDCustomField)
7    .performWithCompletion(^(PNSetUUIDMetadataStatus *status) {
8        if (!status.isError) {
9            /**
10             * UUID metadata successfully has been set.
11             * UUID metadata information available here: status.data.metadata
12             */
13        } else {
14            /**
15             * Handle UUID metadata set error. Check 'category' property to find out possible issue
16             * because of which request did fail.
17             *
18             * Request can be resent using: [status retry]
19             */
20        }
21    });

show all 21 lines

Android

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

C#

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

Python

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

Dart

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

Kotlin

1pubnub.setUUIDMetadata(
2    uuid = "unique uuid",
3    includeCustom = true,
4    name = "Thomas Anderson",
5    email = "t.anderson@pubnub.com",
6    custom = "nickname = The One",
7).async { result, status ->
8            if (status.error) {
9                //handle error
10            } else if (result != null) {
11                //handle result
12            }
13        }

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

1pubnub.objects.setChannelMetadata({
2    channel: "chats_guilds.mages_guild",
3    data: {
4      name: "Mages guild",
5      description: "Mages guild official chatroom.",
6      custom: { "administrator": "thomas_anderson" }
7    }
8});

Swift

1let channelMetadata = PubNubChannelMetadataBase(
2  metadataId: "chats_guilds.mages_guild",
3  name: "Mages guild",
4  channelDescription: "Mages guild official chatroom.",
5  custom: [ "administrator": "thomas_anderson" ]
6)
7

8

9pubnub.set(channel: channelMetadata) { result in
10  switch result {
11  case let .success(metadata):
12    print("The metadata for `\(metadata.metadataId)`: \(metadata)")
13  case let .failure(error):
14    print("Request failed with error: \(error.localizedDescription)")
15  }
16}

show all 16 lines

Objective-C

1self.client.objects().setChannelMetadata(@"chats_guilds.mages_guild")
2    .name(@"Mages guild")
3    .information(@"Mages guild official chatroom.")
4    .custom(@{ @"administrator": @"thomas_anderson" })
5    .includeFields(PNChannelCustomField)
6    .performWithCompletion(^(PNSetChannelMetadataStatus *status) {
7      if (!status.isError) {
8          /**
9           * Channel metadata successfully has been set.
10           * Channel metadata information available here: status.data.metadata
11           */
12      } else {
13          /**
14           * Handle channel metadata update error. Check 'category' property to find out possible
15           * issue because of which request did fail.
16           *
17           * Request can be resent using: [status retry]
18           */
19      }
20    });

show all 20 lines

Java

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

C#

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

Python

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

Dart

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

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

Kotlin

1pubnub.setChannelMetadata(
2    channel = "chats_guilds.mages_guild",
3    includeCustom = true,
4    description = "Mages guild official chatroom",
5    custom = "administrator thomas_anderson"
6).async { result, status ->
7            if (status.error) {
8                //handle error
9            } else if (result != null) {
10                //handle result
11            }
12        }
13

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

1pubnub.objects.setMemberships({
2    channels: [
3        "chats_guilds.mages_guild",
4    {id: "chats_inbox.user_1905", custom: {friendlist: true}
5    }]
6});

Swift

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

6pubnub.setMemberships(uuid: "uuid", channels: channels) { result in
7  switch result {
8  case let .success((memberships, _)):
9    print("Memberships: \(metadata)")
10  case let .failure(error):
11    print("Request failed with error: \(error.localizedDescription)")
12  }
13}

Objective-C

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

6self.client.objects().setMemberships()
7    .uuid(@"uuid")
8    .channels(channels)
9    .includeCount(YES)
10    .limit(40)
11    .includeFields(NMembershipCustomField | PNMembershipChannelField)
12    .performWithCompletion(^(PNManageMembershipsStatus *status) {
13        if (!status.isError) {
14            /**
15             * UUID's memberships successfully set.
16             * Result object has following information:
17             *   status.data.memberships - List of UUID's existing memberships.
18             *   status.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.
19             *   status.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.
20             *   status.data.totalCount - Total number of UUID's memberships.
21             */
22        } else {
23            /**
24             * Handle UUID's memberships set error. Check 'category' property to find out possible
25             * issue because of which request did fail.
26             *
27             * Request can be resent using: [status retry]
28             */
29        }
30    });

show all 30 lines

Android

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

C#

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

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

Python

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

Dart

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

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

Kotlin

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

4pubnub.setMemberships(listOf(
5    PNChannelWithCustom(channel = "chats_guilds.mages_guild"),
6    PNChannelWithCustom(channel = "chats_inbox.user_1905", custom = custom))
7).async { result, status ->
8        if (status.error) {
9            //handle error
10        } else if (result != null) {
11            //handle result
12        }
13    }

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