Channel options
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:
Set channel options
Channel options can be set in two different ways:
- When a channel instance is first obtained using
channels.get(). - Using
channel.setOptions()at any point after the channel instance has been obtained.
channels.get
Pass a 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:
const realtime = new Ably.Realtime('<loading API key, please wait>');
const cipherKey = await realtime.Crypto.generateRandomKey();
const channel = realtime.channels.get('new-due-rub', {cipher: {key: cipherKey}});
Demo OnlyCopyCopied!channel.setOptions
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 setOptions() call.
The following is an example of setting the rewind property to 15 seconds using setOptions():
const realtime = new Ably.Realtime('<loading API key, please wait>');
const channelOpts = {params: {rewind: '15s'}}
await channel.setOptions(channelOpts);
Demo OnlyCopyCopied!Params
The 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
The 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
The 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
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.
As 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:
metrics- this enables events containing the full
occupancydetails in theirdatapayload. 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. metrics.<category>- this enables events whose
datapayload contains anoccupancyvalue 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:
const channelOpts = { params: { occupancy: 'metrics' } };
const channel = ably.channels.get('new-due-rub', channelOpts);
await channel.subscribe('[meta]occupancy', (message) => {
console.log('occupancy: ', message.data);
});
CopyCopied!The following example shows how to subscribe to only subscriber metrics:
const channelOpts = { params: { occupancy: 'metrics.subscribers' } };
const channel = ably.channels.get('new-due-rub', channelOpts);
await channel.subscribe('[meta]occupancy', (message) => {
console.log('occupancy: ', message.data);
});
CopyCopied!The following is an example of an occupancy metric event:
{
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
}
CopyCopied!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 publishers category:
{
name: '[meta]occupancy',
data: {
metrics: {
publishers: 2
}
}
}
CopyCopied!Modes
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:
| Flag | Description |
|---|---|
| SUBSCRIBE | Can subscribe to receive messages on the channel. |
| PUBLISH | Can publish messages to the channel. |
| PRESENCE_SUBSCRIBE | Can subscribe to receive presence events on the channel. |
| PRESENCE | Can register presence on the channel. |
The following is an example of setting channel mode flags:
const realtime = new Ably.Realtime('<loading API key, please wait>');
const channelOptions = {
modes: ['PUBLISH', 'SUBSCRIBE', 'PRESENCE']
};
const channel = realtime.channels.get('new-due-rub', channelOptions);
Demo OnlyCopyCopied!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.
const realtime = new Ably.Realtime('<loading API key, please wait>');
const channelOptions = {
modes: ['PUBLISH', 'SUBSCRIBE', 'PRESENCE']
};
const channel = realtime.channels.get('new-due-rub', channelOptions);
Demo OnlyCopyCopied!Cipher
The 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 [meta?foo=bar]log.
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 "1":
const realtime = new Ably.Realtime('<loading API key, please wait>');
const channel = realtime.channels.get('[?rewind=1]new-due-rub');
Demo OnlyCopyCopied!