Channel Metadata
Overview
Channel Metadata provides information about channels, such as the current state changes of a channel, or the changes in its occupancy. There are several ways to obtain channel metadata:
1. Metachannels – Metachannels are special channels that carry metadata events about all activity associated with an Ably application, which includes metadata associated with channel and connection lifecycle.
2. Inband channel occupancy events – Inband occupancy events are occupancy events relating to a channel that are delivered within the channel itself.
3. Channel Status API – The Channel Status API is a REST API that allows users to query a channel to retrieve channel metadata. It also allows you to enumerate all the active channels in a particular app. The details of the Channel Status API are covered in the Channel Status documentation.
Use cases
Having access to channel metadata can provide numerous benefits. For example, if you want subscribers to be able to track how many other clients are attached to the same channel, and don’t need any of the other features of presence such as being able to enumerate them all and view their presence data, inband occupancy metrics give a simple and lightweight way to do this. Since occupancy is just a simple count of members, this avoids the 200 presence member limit that Ably imposes to prevent presence updates from overwhelming the channel with presence updates.
You may want to publish your data only if there is a subscriber for that data. The channel lifecycle events on metachannels can notify you when a channel is opened, becomes active, or is no longer active, indicating to publisher clients when the last subscriber leaves the channel.
If you need to be able to query channel metadata, you can also make use of the Channel Status API to inspect the state of individual channels, or enumerate all active channels in an app. This is a REST API intended for occasional queries; if you need realtime updates, rather than using a polling approach, Ably recommends you use our realtime metadata APIs.
Tutorials
The tutorials provide step-by-step examples of how to obtain and use channel metadata:
Channel Metadata API Reference
Types
The payload of metadata events for channels is the ChannelDetails
type which contains the channelId
and other static information about the channel, plus a status
containing a ChannelStatus
instance which contains information about the current state of the channel.
ChannelDetails
ChannelDetails
is an object returned when requesting or receiving channel metadata. It contains information on the channel itself, along with the current state of the channel in the ChannelStatus object.
- channelId
- the required name of the channel including any qualifier, if any
Type:string
- region
- in events relating to the activity of a channel in a specific region, this optionally identifies the region
Type:string
- isGlobalMaster
- in events relating to the activity of a channel in a specific region, this optionally identifies whether or not that region is responsible for global coordination of the channel
Type:boolean
- status
- an optional
ChannelStatus
instance
Type: ChannelStatus
{
"channelId": "foo",
"status": {
"isActive": true,
"occupancy": {
"metrics": {
"connections": 1,
"publishers": 1,
"subscribers": 1,
"presenceConnections": 1,
"presenceMembers": 0,
"presenceSubscribers": 1
}
}
}
}
ChannelDetails.ChannelStatus
ChannelStatus
is contained within the ChannelDetails
object, and optionally contains an Occupancy object.
- isActive
- a required boolean value indicating whether the channel that is the subject of the event is active. For events indicating regional activity of a channel this indicates activity in that region, not global activity
Type:boolean
- occupancy
- an optional
Occupancy
instance indicating the occupancy of the channel. For events indicating regional activity of a channel this indicates activity in that region, not global activity.
Type: Occupancy
ChannelDetails.ChannelStatus.Occupancy
Occupancy is optionally contained within the ChannelStatus
object, and contains metadata relating to the occupants of the channel. This is usually contained within the occupancy
attribute of the ChannelStatus
object.
The occupancy
attribute contains the metrics
attribute, which contains the following members:
- connections
- the number of connections
Type:integer
- publishers
- the number of connections attached to the channel that are authorised to publish
Type:integer
- subscribers
- the number of connections attached that are authorised to subscribe to messages
Type:integer
- presenceSubscribers
- the number of connections that are authorised to subscribe to presence messages
Type:integer
- presenceConnections
- the number of connections that are authorised to enter members into the presence channel
Type:integer
- presenceMembers
- the number of members currently entered into the presence channel
Type:integer