Realtime Client Library API

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('xVLyHw.4tXaVA:hKmwl-gRJk3b_AuK');
var channelOpts = {params: {rewind: '1'}};
var channel = realtime.channels.get('eat-tub-rat', channelOpts);
var realtime = new Ably.Realtime('xVLyHw.4tXaVA:hKmwl-gRJk3b_AuK');
var channelOpts = {params: {rewind: '1'}};
var channel = realtime.channels.get('eat-tub-rat', channelOpts);
final Map<String, String> params = new HashMap<>();
params.put("rewind", "1");
final ChannelOptions options = new ChannelOptions();
options.params = params;
final Channel channel = ably.channels.get("eat-tub-rat", options);
let options = ARTClientOptions(key: key)
let client = ARTRealtime(options: options)
let channelOptions = ARTRealtimeChannelOptions()
channelOptions.params = [
  "rewind": "1"
]

let channel = client.channels.get(channelName, options: channelOptions)
var clientOptions = new ClientOptions();
clientOptions.Key = "xVLyHw.4tXaVA:hKmwl-gRJk3b_AuK";
clientOptions.Environment = AblyEnvironment;
var ably = new AblyRealtime(clientOptions);

var channelParams = new ChannelParams();
channelParams.Add("rewind", "1");
var channelOptions = new ChannelOptions();
channelOptions.Params = channelParams;
var channel = ably.Channels.Get("eat-tub-rat", channelOptions);

channel.Subscribe(message => {
    Console.WriteLine(message.Data.ToString());
});

To modify the rewind channel parameters with the value "15s":

var realtime = new Ably.Realtime('xVLyHw.4tXaVA:hKmwl-gRJk3b_AuK');
var channelOpts = {params: {rewind: '15s'}}
channel.setOptions(channelOpts, (err) => {
  if(!err) {
    console.log('channel params updated');
  }
});
var realtime = new Ably.Realtime('xVLyHw.4tXaVA:hKmwl-gRJk3b_AuK');
var channelOpts = {params: {rewind: '15s'}}
channel.setOptions(channelOpts, (err) => {
  if(!err) {
    console.log('channel params updated');
  }
});
final Map<String, String> params = new HashMap<>();
params.put("rewind", "15s");
final ChannelOptions options = new ChannelOptions();
options.params = params;
final Channel channel = ably.channels.get("eat-tub-rat", options);
let options = ARTClientOptions(key: key)
let client = ARTRealtime(options: options)
let channelOptions = ARTRealtimeChannelOptions()
channelOptions.params = [
  "rewind": "15s"
]

let channel = client.channels.get(channelName, options: channelOptions)
var clientOptions = new ClientOptions();
clientOptions.Key = "xVLyHw.4tXaVA:hKmwl-gRJk3b_AuK";
clientOptions.Environment = AblyEnvironment;
var ably = new AblyRealtime(clientOptions);

var channelParams = new ChannelParams();
channelParams.Add("rewind", "15s");
var channelOptions = new ChannelOptions();
channelOptions.Params = channelParams;
var channel = ably.Channels.Get("eat-tub-rat", channelOptions);

channel.Subscribe(message => {
    Console.WriteLine(message.Data.ToString());
});

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('xVLyHw.4tXaVA:hKmwl-gRJk3b_AuK');
const channel = realtime.channels.get('[?rewind=1]eat-tub-rat');

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 "1" using a querystring parameter, where it will apply to all channels:

var querystring = 'v=1.2&channels=eat-tub-rat&rewind=1&key=xVLyHw.4tXaVA:hKmwl-gRJk3b_AuK';
var eventSource = new EventSource('https://realtime.ably.io/event-stream?' + querystring);

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=xVLyHw.4tXaVA:hKmwl-gRJk3b_AuK&channels=' + channels';
var eventSource = new EventSource('https://realtime.ably.io/event-stream?' + querystring);

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

ChannelOptions ObjectARTChannelOptionsio.ably.lib.types.ChannelOptionsIO.Ably.Realtime.ChannelOptions

Channel options are used for setting channel parameters and configuring encryption.

ChannelOptions, a plain Javascript object, may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options. The following attributes can be defined on the object:

ChannelOptions, a Hash object, may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options. The following key symbol values can be added to the Hash:

ChannelOptions, an Associative Array, may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options. The following named keys and values can be added to the Associated Array:

ARTio.ably.lib.types.ChannelOptions may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options.

IO.Ably.ChannelOptions may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options.

PropertiesMembersAttributes

:cipherCipherParamscipher
Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See an example
Type: CipherParams or an options objecta Param[] listan options hashan Associative Array containing at a minimum a key
paramsParams
Optional parameters which specify behaviour of the channel.
Type: Map<String, String>JSON Object
cipherCipherParams
Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See an example
Type: CipherParams or an options objecta Param[] listan options hashan Associative Array containing at a minimum a key

Static methods

withCipherKey

static ChannelOptions.withCipherKey(Byte[] or String key)

A helper method to generate a ChannelOptions for the simple case where you only specify a key.

Parameters

key
A binary Byte[] array or a base64-encoded String.

Returns

On success, the method returns a complete ChannelOptions object. Failure will raise an AblyException.


API reference
Documentation