Connections
Clients establish and maintain a connection to the Ably service using the most efficient transport available, typically WebSockets. Ably SDKs operate and multiplex all channel traffic over that connection. This maximizes throughput, minimizes bandwidth consumption, and reduces power usage. Once connected, clients can monitor and manage their connection state.
Create a connection
Ably SDKs open and maintain a connection to the Ably realtime servers on instantiation, which can be interacted with by using the Connection object. The lifecycle of connections are reported by different connection states to simplify monitoring and managing connections.
This example relies on the default auto-connect behavior of the SDK, checking for when the connection state is connected event:
// Using callbacks
const ably = new Ably.Realtime({ '<loading API key, please wait>' });
ably.connection.on('connected', () => {
console.log('Connected to Ably!');
});
// Using promises
const Ably = require('ably');
const ably = new Ably.Realtime('<loading API key, please wait>');
await ably.connection.once('connected');
console.log('Connected to Ably!');
Demo OnlyCopyCopied!If you’re not using the SDK‘s auto-connect feature you can also connect with connect() to manually connect unless the state is already connected or connecting.
Explicitly calling connect is unnecessary unless the ClientOptions attribute autoConnect is false. Unless already connected or connecting, this method causes the connection to open, entering the connecting state. To manually attempt to open a connection you call the connect() function: ably.connect().
Connection monitoring allows you to view and manage the states of connections to Ably, showing events for individual people connecting and disconnecting. The developer console in your Ably account also shows these events.
This feature is intended for debugging, so once the number of new connections exceeds the number of messages per second permitted by the lifecycle channel, new events will be dropped. This means if you want a definitive list of everyone using your app you’d be best using token authentication to create your own ‘auth server’.
The Ably dashboard contains a developer console. In the developer console you can view connection events.
Connection IDs
A connection ID is a unique identifier given to a connection, allowing for identifying and specifying particular connections.
An active connection ID is guaranteed to be unique in the Ably system whilst it is active, i.e. no other connection will share that connection ID. However, Ably reserves the right to generate a new connection ID later that may be the same as a previously discarded connection ID (once the connection is closed). Therefore we advise customers to not use the connection ID as a perpetual unique identifier as it is possible that a connection ID may be used many times.
Connection metachannels
Metachannels are a namespace of channels beginning with the [meta] qualifier, distinguishing them from regular channels. For connections there is a specific [meta]connection.lifecycle channel that publishes messages about the lifecycle of realtime connections. The connection lifecycle consists of a number of connection states that can be observed and interacted with using methods available on the connection object.
Heartbeats
Heartbeats enable Ably to identify clients that abruptly disconnect from the service, such as where an internet connection drops out or a client changes networks.
Ably sends a heartbeat to connected clients every 15 seconds. If a client goes more than 25 seconds without seeing any server activity from Ably, it assumes that something has gone wrong with the connection and the connection state will become disconnected. The 25 seconds the client waits is the heartbeat interval plus a 10 second margin of error to allow for network delays.
Ably also uses this mechanism to detect dropped client connections, though some details vary depending on the transport used.
It is important to note that this mechanism is only used when something disrupts communication and does not properly terminate the TCP connection. It isn’t used when a connection is deliberately closed or disconnected, for example by calling the close() method or being disconnected by the server.
The 15 second interval between heartbeats is used to strike a balance between optimizing battery usage for client devices and the time it takes to identify a dropped or unstable connection.
The interval between heartbeats can be customized if your app requires increased battery preservation or to identify dropped connections more quickly. Set a value between 5000 and 1800000 milliseconds (5 seconds and 30 minutes) using the heartbeatInterval parameter within the transportParams property of the clientOptions object.
Using a higher heartbeatInterval can increase the time taken for the Ably service and the client itself to identify a connection has dropped when an abrupt disconnect occurs. The number of concurrent connections may also appear higher as it can take longer to terminate dropped connections. Although heartbeatInterval can be set as high as 30 minutes, Ably does not recommend setting it this high.
You can also call ping() to send a heartbeat ping to Ably, which can be useful for measuring the true round-trip latency to the Ably server.
The following example code demonstrates establishing a connection to Ably with a heartbeatInterval of 10 seconds:
const ably = new Ably.Realtime(
{
key: '<loading API key, please wait>',
transportParams: { heartbeatInterval: 10000 }
}
);
Demo OnlyCopyCopied!Close a connection
A connection to Ably should be closed once it is no longer needed. Note that there is a 2 minute delay before a connection is closed, if the close() method hasn’t been explicitly called. This is important to consider in relation to the number of concurrent connections to your account.
The following code sample explicitly closes the connection to Ably by calling the close() method and prints the message Closed the connection to Ably:
ably.close(); // runs synchronously
console.log('Closed the connection to Ably.');
CopyCopied!