Channel subscriptions

Users can subscribe to channels and begin listening for messages on a single socket connection. By default, you can subscribe to a list of up to 100 channels, or use channel groups to subscribe to the list of channels in a channel group.

Subscribing to channels initiates a real-time connection with PubNub. This connection stays open as long as the user remains subscribed from a client application. Any user subscribing to a channel receives messages in under 100ms, regardless of which global region the message was published in.

There are a few sources of real-time updates in PubNub SDKs that provide different levels of granularity, entities being one of them.

Entities

Entity

A subscribable object within a PubNub SDK that allows you to perform context-specific operations.

allow you to create subscriptions to receive all real-time updates associated with that particular entity. The type of received updates is different for each entity type. For more information, refer to Subscriptions.

Subscriptions vs memberships

A subscription isn't the same as a membership: subscriptions allow you to send and receive messages on channels, whereas memberships are metadata about the relationship between users and channels.

Subscribe to channels

The following code samples show a client subscribing to a single channel called chats.room1.

JavaScript

// use a subscription for a single channel
const subscription1 = pubnub.channel('channel_1').subscription({ receivePresenceEvents: true });
subscription1.subscribe();

// use a subscription set for multiple channels
const subscriptionSet = pubnub.subscriptionSet({ channels: ['ch1', 'ch2'] });
subscriptionSet.subscribe();

Swift

// use a subscription for a single channel
let subscription1 = pubnub.channel("channelName").subscription()
subscription1.subscribe()

// use a subscription set for multiple channels
let subscriptionSet = pubnub.subscription(
  entities: [
    pubnub.channel("channel")
  ],
  options: ReceivePresenceEvents()
)
subscriptionSet.subscribe()

Java

pubNub.subscribe()
        .channels(Arrays.asList("ch-1"))
        .withPresence()
        .execute();

Unity

pubnub.Subscribe()
  .Channels(new List<string>() {
    "ch-1"
  })
  .WithPresence()
  .Execute();

Typically, you subscribe to channels on app load. As a user moves around in the app, they stay subscribed to their list of channels so they can continue to receive messages on all their channels.

Subscribe to channel groups

Channel groups are useful in case users in your application need to subscribe to more than 100 channels at a time. By default, your application can create a channel group that holds up to 100 channels. Each user can subscribe to up to 10 channel groups for a total of up to 1,000 channels.

On paid accounts, you can modify that limit for your app in the Admin Portal by changing the value for the Channel group limit on your keyset configuration under the Stream Controller section. You can either lower the default limit of 1,000 channels or increase it up to 2,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.

JavaScript

// use a subscription for a single channel group
const subscription1 = pubnub.channelGroup('channel_group').subscription({ receivePresenceEvents: true });
subscription1.subscribe();

// use a subscription set for multiple channels
const subscriptionSet = pubnub.subscriptionSet({ channelGroups: ['cg1', 'cg2'] });
subscriptionSet.subscribe();

Swift

// use a subscription for a single channel group
let subscription1 = pubnub.channelGroup("channel_group").subscription()
subscription1.subscribe()

// use a subscription set for channel groups
let subscriptionSet = pubnub.subscription(
  entities: [
    pubnub.channelGroup("channelGroup"),
  ],
  options: ReceivePresenceEvents()
)
subscriptionSet.subscribe()

Objective-C

[self.pubnub subscribeToChannelGroups:@["cg_user123"] withPresence:true];

Java

pubnub.subscribe()
  .channelGroups(Arrays.asList("cg_user123"))
  .withPresence()
  .execute();

C#

Subscription subscription1 = pubnub.ChannelGroup("cg_user123").Subscription(SubscriptionOptions.ReceivePresenceEvents)
subscription1.Subscribe<object>()

Python

subscription = pubnub.channel_group('cg_user123').subscription(with_presence = True)
subscription.subscribe()

Managing channel groups

To use a Channel Group, there is just one additional step: add channels to a channel group.

Adding channels to a channel group also creates the channel group if it doesn't already exist. Your server can add 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.

JavaScript

pubnub.channelGroups.addChannels({
    channels: ["chats.room1", "chats.room2", "alerts.system"]
    channelGroup: "cg_user123"
  },
  function(status) {
      console.log(status);
  }
);

Swift

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

Objective-C

[self.pubnub addChannels: @[@"chats.room1", @"chats.room2", @"alerts.system"]
              toGroup:"cg_user123" withCompletion:^(PNAcknowledgmentStatus *status) {
    // handle success/error
}];

Java

pubnub.addChannelsToChannelGroup()
  .channelGroup("cg_user123")
  .channels(Arrays.asList("chats.room1", "chats.room2", "alerts.system"))
  .async(result -> { /* check result */ });

C#

pubnub.AddChannelsToChannelGroup()
  .ChannelGroup("cg_user123")
  .Channels(new string[] {"chats.room1", "chats.room2", "alerts.system"})
  .Execute(new PNChannelGroupsAddChannelResultExt((result, status) => {
      // handle success/error
    }
  ));

Python

pubnub.add_channel_to_channel_group()\
  .channels(["chats.room1", "chats.room2", "alerts.system"])\
  .channel_group("cg_user123")\
  .sync()