Channel Parameters
Overview
Ably provides channel parameters as a means of customizing channel functionality. For example, you can request that a channel attachment start from some time in the past by using the rewind parameter.
The methods provided for specifying channel parameters are outlined below.
Supported channel parameters
A set of channel parameters is a set of key/value pairs, where both keys and values are strings; the keys correspond to specific features that Ably defines:
- rewind
- Allows an attachment to a channel to start from a given number of messages or point in time in the past. See rewind for more information.
- delta
- Enables delta compression, a way for a client to subscribe to a channel so that message payloads sent contain only the difference (ie the delta) between the present message and the previous message on the channel. See deltas for more information.
Using channel parameters with Ably libraries
You can specify channel parameters in the ChannelOptions
when obtaining a Channel
. A collection of channel parameters is expressed as a map of string key/value pairs. The ChannelOptions
associated with a channel may also be updated by calling setOptions. The parameters associated with a channel take effect when the channel is first attached; if the parameters are subsequently modified via a call to setOptions
, then that call triggers an attach operation that applies the updated parameters, if successful.
Example
For example, to specify the rewind
channel parameter with the value "1"
:
var realtime = new Ably.Realtime('<loading API key, please wait>');
var channelOpts = {params: {rewind: '1'}};
var channel = realtime.channels.get('ray-map-ash', channelOpts);
Demo OnlyCopyCopied!
To modify the rewind
channel parameters with the value "15s"
:
var realtime = new Ably.Realtime('<loading API key, please wait>');
var channelOpts = {params: {rewind: '15s'}}
channel.setOptions(channelOpts, (err) => {
if(!err) {
console.log('channel params updated');
}
});
Demo OnlyCopyCopied!
Using channel parameters without Ably library support
For the client libraries that do not currently expose the API, or transports that do not involve using an Ably library, a set of channel parameters 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.
Examples of transports that do not use Ably libraries include using SSE without any library, or using a supported non-Ably protocol such as MQTT
To specify the parameter 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
.
Example of Ably library without channel parameters support
Using this syntax with a non-supported Ably library means that channel parameters are specified for the lifetime of the Channel
instance; in order to reference the same channel, but with different channel parameters, it is necessary to get a new Channel
instance, using a qualified name that includes the new channel parameters.
For example, to specify the rewind
channel parameter with the value "1
:
const realtime = new Ably.Realtime('<loading API key, please wait>');
const channel = realtime.channels.get('[?rewind=1]ray-map-ash');
Demo OnlyCopyCopied!
SSE example
In an SSE connection, it is also possible to specify channel parameters as a query string in the connection URL, instead of as a qualifier on an individual channel name. In this case, the given channel parameters apply to all channel attachments associated with that connection.
For example, to specify the rewind
channel parameter with the value "
using a querystring parameter, where it will apply to all channels:
var querystring = 'v=1.2&channels=ray-map-ash&rewind=1&key=<loading API key, please wait>';
var eventSource = new EventSource('https://realtime.ably.io/event-stream?' + querystring);
Demo OnlyCopyCopied!
Or to specify the same parameter but only applying to one channel of two, using a qualified channel name:
var channelOne = encodeURIComponent('[?rewind=1]channel1');
var channelTwo = 'channel2';
var channels = channelOne + ',' + channelTwo;
var querystring = 'v=1.2&key=<loading API key, please wait>&channels=' + channels';
var eventSource = new EventSource('https://realtime.ably.io/event-stream?' + querystring);
Demo OnlyCopyCopied!
Next steps
- Request that an attachment start from a given number of messages or point in time in the past using rewind.
- Request that data payloads should be sent as deltas to the previous payload using deltas.
API Reference
View the Channel Options API Reference.