Membership Metadata

Manage membership with BizOps Workspace

You can manage user-channel membership using BizOps Workspace on Admin Portal that lets you add, update, or remove users from channels on your apps' keysets.

Apart from users and channels, PubNub also allows you to store the relations between them called memberships. Each user that you add to a channel becomes a member of that specific channel.

Memberships and subscriptions

Adding channel memberships to a user isn't the same as subscribing to a channel by that user. The act of adding channel memberships doesn't result in receiving messages sent to that channel. To receive messages, subscribe.

Persisting membership information isn't necessary to send or receive messages, but comes in handy when you want to keep track of the subscribers of a particular channel. Using a membership association, your application can display channel memberships lists for each user or give the user the possibility to join or leave channels at their discretion, for example.

When a user opens a in-app messaging app and joins a few channels they're interested in, they're expressing the desire to change their current memberships - it's always the user who wants to manage their memberships. Because of this, membership methods take the current client's User ID by default unless another user's User ID is explicitly specified.

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 emits events to notify clients when users are added to or removed from a channel. You can enable this feature using the Admin Portal. In the App Context section, select or clear the appropriate checkboxes to enable or disable sending particular events.

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.

The App Context service allows you to perform the following operations on memberships:

Channel Memberships​

OperationDescription
Set channel membershipsAdds the current user to one or more channels or updates the custom metadata for the existing memberships. This operation creates a membership for the user to the specified channels.
Remove channel membershipsRemoves the current user from one or more channels. This operation removes a membership for the user from the specified channels.
Get channel membershipsReturns a list of channel memberships for the current user.

Set Channel Memberships​

You can add a single user to one or more channels (effectively creating a membership relation between the user and the channels) or update the custom metadata of the user's one or more existing memberships. To update custom metadata of existing memberships, provide the desired information as key/value pairs.

API limits

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

The code below adds the current user to the channels my_channel and my_channel_2 and adds the starred metadata to the newly created my_channel_2 membership.

pubnub.objects.setMemberships({
    channels: [
    "channel-1",
    {id: "channel-2", custom: {starred: true}
    }]
});

On success, the PubNub SDK will return the channel data for all the specified channels along with the status 200. It will also fire the objects -> membership -> set event so it can be consumed for other clients (users).

Referential integrity

Enabling referential integrity on your app’s keyset in the Admin Portal ensures that memberships can only be created for existing users and channels, and automatically deletes memberships when their associated user or channel is deleted.

If it’s not enabled, memberships can be created even for the non-existent user and channel entities, while deleting a user or channel entity does not automatically delete any associated membership objects.

Remove Channel Memberships​

You can remove a single user from one or more channels, effectively deleting a membership relation between the user and the channels. The code below removes the current user from the channel my_channel_2.

pubnub.objects.removeMemberships({
  channels: ["my_channel_2"]
});

On completion, the PubNub SDK will fire the objects -> membership -> delete event so it can be consumed for other clients (users). Refer to the Receive Messages to learn more.

Get Channel Memberships​

You can retrieve a list of channel memberships for the current user. The code below returns all memberships for the current user.

pubnub.objects.getMemberships();

On success, the PubNub SDK will return the all channels for which the user is a member along with the status 200.

Channel Member​

Apart from users and channels, PubNub also allows you to store the relations between them called memberships. Each user that you add to a channel becomes a member of that specific channel.

The following section describes how to add channel memberships from an external user's perspective, that is, when another user wants to add/remove members to a channel. This is the case when a user already is a member (or a moderator) of a specific channel and wishes to add/remove users to that channel. Setting members in a channel is also a more efficient way of handling bulk operations than setting memberships.

PubNub emits events to notify clients when users are added to or removed from a channel. You can enable this feature using the Admin Portal. In the App Context section, select or clear the appropriate checkboxes to enable or disable sending particular events.

The App Context service allows you to perform the following operations on channel members:

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.

OperationDescription
Set members in channelAdds one or more users to a single channel. This operation creates memberships for these users to the specified channel.
Remove members from channelRemoves one or more users from a single channel. This operation removes memberships for these users from the specified channel.
Get members in channelReturns a list of users on a single channel. The list includes user's custom metadata if available and includes only User IDs for users who do not have custom metadata.

Set Members in Channel​

You can add one or more users to a single channel (effectively creating a membership relation between the users and the channel) or update the custom metadata of one or more users that are existing members of a single channel. To update custom metadata of existing memberships, provide the desired information as key/value pairs.

API limits

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

The code below adds the membership to my_channel for the users johndoe_1 and janedoe_1. Additionally, custom metadata trialPeriod is also added to the newly created membership for janedoe_1.

pubnub.objects.setChannelMembers({
  channel: "my_channel",
  uuids: [
    'johndoe_1',
    { id: 'janedoe_1', custom: { trialPeriod: false } },
  ],
});

On success, the PubNub SDK will return the channel data of the specified channel along with the status 200. It will also fire the objects -> membership -> set event so it can be consumed for other clients (users). Refer to the Receive Messages to learn more.

Referential integrity

Enabling referential integrity on your app’s keyset in the Admin Portal ensures that memberships can only be created for existing users and channels, and automatically deletes memberships when their associated user or channel is deleted.

If it’s not enabled, memberships can be created even for the non-existent user and channel entities, while deleting a user or channel entity does not automatically delete any associated membership objects.

Remove Members from Channel​

You can remove one or more users from a single channel by providing the channel ID and a list of users. The code below deletes the membership to my_channel_2 for the users johndoe_1 and janedoe_1.

pubnub.objects.removeChannelMembers({
        channel: "my_channel_2",
        uuids: ["johndoe_1", "janedoe_1"]
    }
);

On completion, the PubNub SDK will fire objects -> membership -> delete event.

Get Members in Channel​

You can retrieve a list of members of a single channel simply by providing its ID. The code below returns the members of the channel my_channel.

pubnub.objects.getChannelMembers({
    channel: "my_channel"
});

On success, the PubNub SDK returns the UUIDs of all the users, and the associated channel metadata for that channel, along with the status 200.

Last updated on
Related Resources
On this page