Channel Subscription
As PubNub allows you to subscribe to hundreds or even thousands of channels, it's vital to understand how to efficiently manage them. The sections on this page focus on the different ways you can subscribe to multiple channels with channel groups, wildcards, and Message Filters.
Receiving messages
To receive and handle incoming messages, signals, and events, you have to add an event listener first.
If you're new to PubNub, make sure to check out how to set up your account as well.
Subscribe to Channels
Once the listener object is established, the client can start issuing requests to subscribe to individual channels. Subscribing to channels initiates a connection with the PubNub Platform which triggers a connection status event. This connection is kept open for the duration that the client stays subscribed to at least one channel. Any user subscribing to a channel will receive messages in under 100ms, regardless of which global region the message was sent.
Default subscribe timeout
There is a default timeout of 310 seconds (~5 min) for all requests related to subscribed channels that the client sends to the server. You can reduce this limit in your client configuration by specifying a different value for the subscribeTimeout
parameter.
The client can subscribe to several channels simultaneously through a single open connection. Typically, you subscribe to channels on app load. As the user navigates through your app, your app can remain subscribed to all the channels so it continues to receive messages on all of them. Alternatively, you can implement your app in a way that it subscribes and unsubscribes from channels as the user navigates through the app.
- JavaScript
- Swift
- Objective-C
- Android
- C#
- Python
pubnub.subscribe({channels: ["chats.room1", "alerts.system"]});
pubnub.subscribe(to: ["chats.room1", "alerts.system"])
[self.pubnub subscribeToChannels: @[@"chats.room1", @"alerts.system"] withPresence:NO];
pubnub.subscribe().channels(Arrays.asList("chats.room1", "alerts.system"));
pubnub.Subscribe<string>()
.Channels(new string[] {"chats.room1", "alerts.system"})
.Execute();
pubnub.subscribe()\
.channels("chats.room1", "alerts.system")\
.execute()
Signal Channel Subscribe
To receive Signals, you don't need a different subscription to the channel, but you do need a separate signal
event handler as mentioned in the Adding a Listener section.
Channel Multiplexing
Subscribing to multiple channels from a single client is called multiplexing. You can subscribe to one or more channels by providing the channel names as an array of strings. Multiplexing allows each client to subscribe to a combination of channels of their choosing and change that selection at any time.
Multiplexing is designed for a relatively small number of channels. While there is no hard limit, PubNub strongly recommends multiplexing no more than 30 channels for any subscribe, and possibly fewer if you are deploying a larger application. For bigger channel subscribe groupings, you should consider using Channel Groups.
You can subscribe to one or more channels in a single request or you can spread those requests out in your application's flow. For example, a client might subscribe to chats.room1
now and then later subscribe to chats.room2
. Doing so will simply add chats.room2
to the current list of channels that have already been subscribed as if you subscribed to them at the same time.
For example, below is how you would subscribe to a channel chats.room1
when the user of your app enter their first chat room.
- JavaScript
- Swift
- Objective-C
- Android
- C#
- Python
pubnub.subscribe({channels: ["chats.room1"]});
pubnub.subscribe(to: ["chats.room1"])
[self.pubnub subscribeToChannels: @[@"chats.room1"] withPresence:NO];
pubnub.subscribe().channels(Arrays.asList("chats.room1"));
pubnub.Subscribe<string>()
.Channels(new string[] {"chats.room1"})
.Execute();
pubnub.subscribe()\
.channels("chats.room1")\
.execute()
The user continues to use your application, and then decides to enter another chat room, chats.room2
.
- JavaScript
- Swift
- Objective-C
- Android
- C#
- Python
pubnub.subscribe({channels: ["chats.room2"]});
pubnub.subscribe(to: ["chats.room2"])
[self.pubnub subscribeToChannels: @[@"chats.room2"] withPresence:NO];
pubnub.subscribe().channels(Arrays.asList("chats.room2"));
pubnub.Subscribe<string>()
.Channels(new string[] {"chats.room2"})
.Execute();
pubnub.subscribe()\
.channels("chats.room2")\
.execute()
The result is that the user is now subscribed to both chat room channels.
You can also leverage Channel Groups and Wildcard Subscribe. Below you'll be briefly introduced to these two alternative subscription management features.
Enable Access Manager
Multiplexing is available by default, regardless of your Admin Portal configuration. However, to use the Wildcard Subscribe and Channel Groups features, the Stream Controller add-on must be enabled on your keyset in the Admin Portal.
Channel Groups
You can think of a channel group like a pointer to a list of channels on your server. If your application requires listening to large numbers of channels at once, channel groups allow you to send a single call which may subscribe to up to 2000 channels. Each individual client can subscribe to a maximum of 10 channel groups for a total of up to 20,000 channels.
Channel Group operations
You can't publish to a Channel Group. You can only subscribe to it. To publish within Channel Group, you need to publish to each channel individually.
Subscribe vs. Publish to Channel Groups
Channel groups can also be thought of as a Subscribe Group, because you can only subscribe to a channel group; you can't publish to a channel group. There are definite advantages to using channel groups when your clients must subscribe to a lot of channels. Your server adds channels to a channel group and clients can subscribe to all those channels contained in the channel group simply by subscribing to that channel group.
Your clients may not need to listen to that many channels, but channel groups make it possible for your server to manage the channels that the client is subscribed to by adding and removing channels on behalf of the clients.
To use a channel group, instead of multiplexing, there is just one additional step: add channels to a channel group.
Add channels to a channel group. This also creates the channel group if it doesn't already exist. This should be performed by your server for security and ease of management.
- JavaScript
- Swift
- Objective-C
- Android
- C#
- Python
pubnub.channelGroups.addChannels({
channels: ["chats.room1", "chats.room2", "alerts.system"]
channelGroup: "cg_user123"
},
function(status) {
console.log(status);
}
);
pubnub.add(
channels: ["chats.room1", "chats.room2", "alerts.system"],
to: "cg_user123"
) { result in
switch result {
case let .success(response):
print("succeeded: \(response)")
case let .failure(error):
print("failed: \(error.localizedDescription)")
}
}
[self.pubnub addChannels: @[@"chats.room1", @"chats.room2", @"alerts.system"]
toGroup:"cg_user123" withCompletion:^(PNAcknowledgmentStatus *status) {
// handle success/error
}];
pubnub.addChannelsToChannelGroup()
.channelGroup("cg_user123")
.channels(Arrays.asList("chats.room1", "chats.room2", "alerts.system"))
.async(new PNCallback<PNChannelGroupsAddChannelResult>() {
@Override
public void onResponse(PNChannelGroupsAddChannelResult result, PNStatus status) {
if (status.isError()) {
System.out.println("failed: " + status.getMessage());
}
else System.out.println("succeeded");
}
});
pubnub.AddChannelsToChannelGroup()
.ChannelGroup("cg_user123")
.Channels(new string[] {"chats.room1", "chats.room2", "alerts.system"})
.Execute(new PNChannelGroupsAddChannelResultExt((result, status) => {
// handle success/error
}
));
pubnub.add_channel_to_channel_group()\
.channels(["chats.room1", "chats.room2", "alerts.system"])\
.channel_group("cg_user123")\
.sync()
The client subscribes to the channel group.
- JavaScript
- Swift
- Objective-C
- Android
- C#
- Python
pubnub.subscribe({
channelGroups: ["cg_user123"],
withPresence: true
});
pubnub.subscribe(
to: [],
and: ["cg_user123"],
withPresence: true
)
[self.pubnub subscribeToChannelGroups:@["cg_user123"] withPresence:true];
pubnub.subscribe()
.channelGroups(Arrays.asList("cg_user123"))
.withPresence()
.execute();
pubnub.Subscribe<string>()
.ChannelGroups(new string[] {"cg_user123"})
.WithPresence()
.Execute();
pubnub.subscribe()\
.channel_groups("cg_user123")\
.with_presence()\
.execute()
When messages are published to any of the channels in this channel group, it will be received in the message handler of the client's listener. The channel group subscribes can also be enabled with withPresence
parameter to start receiving presence events for all the channels in the Channel Group. Be aware of whether this is necessary for your use case or not. You can separate channels into two channels groups: cg_presence_user123
(channels with presence tracking) and cg_user123
(channels without presence tracking). This can all be done on the client app. but when we talk about channel access security (Access Manager), it will be clear why clients should never be able to add/remove channels to/from a channel group.
Additionally, with Channel Groups your server can force a client to unsubscribe from a particular channel just by removing that channel from the channel group that the client is subscribed to.
Channel Group Names
Channel groups can be shared just like channels. For example, you may want to create a channel group called cg_sports
. Multiple clients can subscribe to this shared channel group and your server can add new channels related to sports and all the clients will automatically be subscribed to those new channels.
And there is no requirement to prefix the name with cg_
. It's only a convention that makes it easy to recognize Channel Groups. Feel free to use a naming convention that works best for your requirements and design style.
Channel Group Names
Channel Group names have the same rules as Channel names with one exception: you can't use a period in the name. This means that wildcard features do not apply to Channel Groups.
Just because you're using Channel Groups does not mean you can't also subscribe to individual channels. Sometimes it may be convenient to subscribe to a particular channel directly while also subscribing to a separate Channel Group. You can specify channels and channel groups in the same subscribe call or make individual subscribe calls. And channel groups can be multiplexed, too.
Wildcard Subscribe
Wildcard Subscribe channelName.*
can be used to subscribe to a hierarchical list of channels. It's similar to Channel Group in that you can subscribe to lots of channels with a single name declaration. For example, you specify a wildcard channel pattern like sports.*
, and your app will subscribe to all channel names that match that pattern: sports.cricket
, sports.lacrosse
. This list can be virtually infinite in number with some limitations described in the next section.
- JavaScript
- Swift
- Objective-C
- Android
- C#
- Python
pubnub.subscribe({
channels: ["alerts.*", "chats.team1.*"],
withPresence: true
});
pubnub.subscribe(
to: ["alerts.*", "chats.team1.*"],
and: [],
withPresence: true
)
[self.pubnub subscribeToChannels: @[@"alerts.*", @"chats.team1.*"] withPresence:YES];
pubnub.subscribe()
.channels(Arrays.asList("alerts.*", "chats.team1.*")
.withPresence());
pubnub.Subscribe<string>()
.Channels(new string[] {"alerts.*", "chats.team1.*"})
.WithPresence()
.Execute();
pubnub.subscribe()\
.channels("alerts.*", "chats.team1.*")\
.with_presence()\
.execute()
Wildcard Subscribe Rules
There are some limits to what you can do with the Wildcard Subscribe. Below is a quick summary of the rules:
- You're limited to two dots (three levels). For example, you can subscribe to
a.*
ora.b.*
but nota.b.c.*
. - A wildcard pattern must always end with
.*
. In other words, the*
can't be in the middle of the pattern (a.*.c
, isn't valid). - Just like Channel Groups, you can not publish to a wildcard channel pattern.
Message Filters
With the metadata information being sent with the published message, we can now leverage Message Filters to omit messages that aren't important for a particular client. For example, filter out messages that the client published using its User ID.
In the following code examples, the userId
variable is used as a placeholder variable that would hold the User ID value for the client. For your servers, this value would be pulled from a server config file. For your clients, this value is received from your server after successful login.
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
- Swift
- Objective-C
- Android
- C#
- Python
var pubnub = new PubNub({
publishKey: "myPublishKey",
subscribeKey: "mySubscribeKey"
userId: userId
})
pubnub.setFilterExpression("userId != '" + pubnub.getUserId() + "'");
// the userId value is received from your server
var pnconfig = PubNubConfiguration(
publishKey: "myPublishKey",
subscribeKey: "mySubscribeKey",
)
pnconfig.userId: userId
pnconfig.filterExpression: "userId != \(userId)"
var pubnub = PubNub(configuration: pnconfig)
// the uuid value is received from your server
PNConfiguration *pnconfig = [PNConfiguration configurationWithPublishKey:@"myPublishKey"
subscribeKey:@"mySubscribeKey"];
pnconfig.uuid = uuid;
self.pubnub = [PubNub clientWithConfiguration:pnconfig];
NSString *filterExp = [NSString stringWithFormat:@"uuid != '%@'",
self.pubnub.currentConfiguration.uuid];
[self.pubnub setFilterExpression:filterExp];
// the UserId value is received from your server
PNConfiguration pnconfig = new PNConfiguration();
pnconfig.setPublishKey("myPublishKey");
pnconfig.setSubscribeKey("mySubscribeKey");
pnConfiguration.setUserId(new UserId("myUniqueUserId"));
pnconfig.setFilterExpression("userId != '" + pnconfig.getUserId() +"'");
PubNub pubnub = new PubNub(pnconfig);
PNConfiguration pnconfig = new PNConfiguration();
pnconfig.PublishKey = "myPublishKey";
pnconfig.SubscribeKey = "mySubscribeKey";
pnconfig.UserId = UserId;
pnconfig.FilterExpression = "UserId != '" + pnconfig.GetCurrentUserId() + "'";
Pubnub pubnub = new Pubnub(pnconfig);
pnconfig = PNConfiguration()
pnconfig.publish_key = "myPublishKey"
pnconfig.subscribe_key = "mySubscribeKey"
pnconfig.user_id = user_id
pnconfig.filter_expression = "user_id !='" + user_id +"'"
pubnub = PubNub(pnconfig)
To learn more about the filter options, refer to the table in the Publish messages section.
Unsubscribe from Channels
Unsubscribe from a channel to stop receiving its messages. You can use this method to unsubscribe from one or more channels.
- JavaScript
- Swift
- Android
- Unity
pubnub.unsubscribe({
channels: ['ch-1']
})
pubnub.unsubscribe(from: ["ch-1"])
pubnub.unsubscribe()
.channels(Arrays.asList("ch-1"))
.execute();
pubnub.Unsubscribe<string>()
.Channels(new string[] {
"ch-1"
})
.Execute();
Unsubscribe from all Channels
Use this method to unsubscribe from all channels.
- JavaScript
- Swift
- Android
- Unity
pubnub.unsubscribeAll();
pubnub.unsubscribeFromAll()
pubNub.unsubscribeAll();
pubnub.UnsubscribeAll().Async((result, status) => {
if (!status.Error) {
Debug.Log(result.Message);
} else {
Debug.Log(status.Error);
Debug.Log(status.ErrorData.Info);
}
});
Status events
When channels are subscribed, connections are disconnected, reconnected or when connection errors are encountered, status events are generated and clients can receive those events in the listener's status
handler.
Most SDKs provide an operation and category as part of a status event. The supported categories may vary with each language and platform, and some SDKs may have a more robust architecture than others. The differences will be noted as necessary.
Handle Status Events
The Event listener and its handlers are briefly mentioned in Receive Messages. Compared to other event types, status events are more focused on connection status and subscribe request errors, like permission denied, message decryption, and more.
- JavaScript
- Swift
- Objective-C
- Android
- C#
- Python
Because the browser can detect when the connection is lost and restored, the JavaScript SDK (when running in a browser) has two additional events that allow you to explicitly handle those scenarios: PNNetworkDownCategory
and PNNetworkUpCategory
. Other environments do not support this real-time network status behavior.
The following data can be extracted from a JavaScript SDK status event.
pubnub.addListener({
status: function(event) {
var affectedChannelGroups = event.affectedChannelGroups;
var affectedChannels = event.affectedChannels;
var category = event.category;
var operation = event.operation;
var lastTimetoken = event.lastTimetoken;
var currentTimetoken = event.currentTimetoken;
var subscribedChannels = event.subscribedChannels;
}
});
For more details on handling Status Events, visit the JavaScript SDK Status Events documentation page.
The iOS-based SDKs have the most robust status event architecture. There are many more event types that allow you to more explicitly handle each scenario. The following is just a subset of the events which focus on connection and subscribe scenarios.
let listener = SubscriptionListener()
listener.didReceiveSubscription = { e in
switch e {
case statusReceived(event):
print("Status Received: \(event)")
case subscriptionChanged(event):
print("Subscribe Changed: \(event)")
case subscribeError(event):
print("Subscription Error \(event.localizedError)")
}
}
show all 16 linesFor more details on handling Status Events, visit the Swift SDK Status Events documentation page.
The iOS-based SDKs have the most robust status event architecture. There are many more event types that allow you to more explicitly handle each scenario. The following is just a subset of the events which focus on connection and subscribe scenarios.
While all the status events are passed into the didReceiveStatus
delegate, there are many operations and categories that you can leverage to determine how to handle the given scenario.
[self.pubnub addListener:self];
- (void)client:(PubNub *)pubnub didReceiveStatus:(PNStatus *)event {
NSString *operation = event.operation;
NSString *category = event.category;
}
For more details on handling Status Events, visit the Objective-C SDK Status Events documentation page.
SubscribeCallback
is an Abstract Java class, and requires that you implement all Abstract methods of the parent class. For clarity, the following sample code shows only one of the methods.
pubnub.addListener(new SubscribeCallback() {
@Override
public void status(PubNub pubnub, PNStatus event) {
String operation = event.getOperation();
String category = event.getCategory();
}
});
For more details on handling Status Events, visit the Android SDK Status Events documentation page.
SubscribeCallbackExt subscribeCallack = new SubscribeCallbackExt(
delegate (Pubnub pubnubObj, PNStatus event) {
string operation = event.Operation;
string category = event.category;
}
);
pubnub.AddListener(subscribeCallack);
For more details on handling Status Events, visit the C# SDK Status Events documentation page.
class SubscribeHandler(SubscribeCallback):
def status(self, pubnub, event):
pass
pubnub.add_listener(SubscribeHandler())
For more details on handling Status Events, visit the Python SDK Status Events documentation page.