Inband channel occupancy events

The inband channel occupancy feature allows a client to subscribe to occupancy metadata events relating to a single channel, and for those events to be delivered to the client as messages on the channel itself. Occupancy metadata events received as messages on the channel are known as inband events.

The Occupancy type is defined in the Channel Metadata documentation.

Inband channel occupancy events are enabled in a channel attachment by specifying the occupancy parameter. This is described in more detail in the Channel Parameters documentation. The value of the parameter specifies the occupancy fields of interest, and the supported parameter values are:

• metrics: this enables events containing the full Occupancy details in their data payload. Events are sent when the count for any of the included categories changes. Updates that involve mode changes (for example, at least one publisher existing where there were none before) are propagated immediately; ones that do not are debounced, for no more than 15 seconds.
• metrics.<category>: this enables events whose data payload contains an Occupancy value containing the occupancy, that is the client count, for only the given category. Events are sent when the count for any of the included categories changes. Updates that involve mode changes (for example, at least one publisher existing where there were none before) are propagated immediately; ones that do not are debounced, for no more than 15 seconds.

Channel parameters are a general mechanism for specifying attributes of a channel attachment. See the Channel parameters documentation for further details.

The following example shows how to specify the occupancy channel parameter:

let channelOpts = { params: { occupancy: 'metrics' } };
let channel = ably.channels.get('ray-map-ash', channelOpts);

Copy
Copied!

In this case all occupancy metrics are contained in occupancy messages.

The following example shows how to specify a category:

let channelOpts = { params: { occupancy: 'metrics.subscribers' } };
let channel = ably.channels.get('ray-map-ash', channelOpts);

Copy
Copied!

In this case only occupancy metrics for subscribers are contained in occupancy messages.

You need the channel-metadata capability for the channel for which you want to receive occupancy events. You can set this for your API key using the Ably dashboard, or you can set it using a capability added to a token request. See the capability documentation for further details.

Events in a channel that contain metadata have an event name qualified with the [meta]prefix. For example, occupancy messages have an event name of [meta]occupancy. Messages published by clients do not contain this metadata. The following code snippet illustrates this:

let channelOpts = { params: { occupancy: 'metrics' } };
let channel = ably.channels.get('ray-map-ash', channelOpts);


channel.subscribe('[meta]occupancy', (message) => {
  console.log('inband: ', message.data);
});

Copy
Copied!

In this example only occupancy messages are logged to the console.

An example inband channel occupancy message is shown here:

{
  name: '[meta]occupancy',
  id: 'V12G5ABc_M:0:0',
  timestamp: 1612286351217,
  clientId: undefined,
  connectionId: undefined,
  connectionKey: undefined,
  data: {
    metrics: {
      connections: 1,
      publishers: 1,
      subscribers: 1,
      presenceConnections: 1,
      presenceMembers: 0,
      presenceSubscribers: 1
    }
  },
  encoding: null,
  extras: undefined,
  size: undefined
}

Copy
Copied!

Occupancy events have a payload in their data attribute which is an Occupancy value. An example of the occupancy event data is shown here:

{
  metrics: {
    connections: 4,
    publishers: 4,
    subscribers: 4,
    presenceConnections: 4,
    presenceMembers: 2,
    presenceSubscribers: 4
  }
}

Copy
Copied!

If subscribing to only a single category, then only that member is present, as shown in the following example for the subscribers category:

{
  name: '[meta]occupancy',
  data: {
    metrics: {
      subscribers: 2
    }
  }
}

Copy
Copied!

Please refer to the following resources for more information:

• Inband channel occupancy tutorial
• Channel metadata
• Metachannels
• Channel parameters documentation