Channel options can be used to customize the functionality of channels. This includes enabling features such as encryption and deltas, or for a client to retrieve messages published prior to it attaching to a channel using rewind.
Channel options are set under the following properties:
Channel options can be set in two different ways:
- When a channel instance is first obtained using
channel.setOptions()at any point after the channel instance has been obtained.
channelOptions object into the call to
get() in order to set the desired channel options when obtaining a channel instance.
The following is an example of setting the
cipher property to set encryption when obtaining a channel instance:
You can modify the
channelOptions associated with a given channel instance by calling
setOptions() and passing a new
channelOptions object. The modified options will either take effect at the time of attachment, if an attach for that channel has not yet been initiated, or the
setOptions() call will trigger an immediate attach operation to apply the modified options. Success or failure of any triggered attach operation is indicated in the result of the
The following is an example of setting the
rewind property to 15 seconds using
params property can be used to enable additional features on a channel-by-channel basis. These features include using
rewind to replay messages published prior to a client attaching to a channel,
delta so that message payloads only contain the difference between the current and previous message, and
occupancy to subscribe to metrics about the clients attached to a channel.
rewind feature enables clients to replay messages that were published to the channel prior to that clients attachment. This can be by a specific number of messages, or a by a period of time.
delta feature enables clients to subscribe to a channel so that message payloads only contain the difference, or delta, between the current and previous message.
Occupancy provides metrics about the clients attached to a channel, such as the number of connections and the number of clients subscribed to the channel.
occupancy can be specified in the
params property in order to subscribe a client to occupancy metrics for the channel. The metrics will be received by a client as events on the channel.
occupancy requires a channel subscription, it is only available when using the realtime interface of an Ably SDK.
The value of the
occupancy property can be set depending on the metrics you want to subscribe to:
- this enables events containing the full
occupancydetails in their
datapayload. 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. Updates that do not involve a mode change are debounced, for no more than 15 seconds.
- this enables events whose
datapayload contains an
occupancyvalue 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. Updates that do not involve a mode change are debounced, for no more than 15 seconds.
Occupancy metrics have an event name of
[meta]occupancy which can be used to subscribe to that event type when registering a listener.
The following example shows how to subscribe to all occupancy metrics:
The following example shows how to subscribe to only subscriber metrics:
The following is an example of an occupancy metric event:
Occupancy events have a payload in the
data property with a value of
occupancy. If a client only subscribes to a single metric category, then only that member is present. For example if only subscribing to the
modes property can be used to set channel mode flags. Channel mode flags enable a client to specify a subset of the capabilities granted by their token or API key. Channel mode flags offer the ability for clients to use different capabilities for different channels, however, as they are flags and not permissions they cannot be enforced by an authentication server.
The channel mode flags available are:
|Can subscribe to receive messages on the channel.
|Can publish messages to the channel.
|Can subscribe to receive presence events on the channel.
|Can register presence on the channel.
The following is an example of setting channel mode flags:
A common use case for channel mode flags is to provide clients the ability to be present on a channel, without subscribing to presence events.
The following example demonstrates this use case, where the client would be present on the channel without receiving presence notifications from other clients in the presence set. As this is server-side filtering, clients won’t be receiving presence notifications which saves a potentially high volume of messages from being used.
cipher property can be used to enable message encryption. This ensures that message payloads are opaque and can only only be decrypted by other clients that share your secret key.
For any Ably SDKs that do not currently expose the channel options API, a set of channel options can be expressed by including a query string with standard URL query syntax and encoding, within the qualifier part of a channel name. The qualifier part is in square brackets at the start of the channel name.
To specify the channel option
foo with value
bar on channel
baz, the qualified channel name would be
[?foo=bar]baz. If the channel name already has a qualifier, such as
[meta]log, then the query string follows the existing qualifier, as in
Using this syntax with a non-supported Ably SDK means that channel options are specified for the lifetime of the
Channel instance. In order to reference the same channel, but with different options, it is necessary to get a new
Channel instance, using a qualified name that includes the new channel options.
For example, to specify the
rewind channel option with the value