API v 0.8
JavaScript

Connection

The Connection object exposes the following public properties:

A unique public identifier String for this connection, used to identify this member in presence events and messages.

The current state String of this Connection. See the Connection states for more information.

When a connection failure occurs this attribute contains the .

A unique private connection key String used to recover or resume a connection, assigned by Ably. When recovering a connection explicitly, the recoveryKey is used in the recover client options as it contains both the key and the last message serial.

This private connection key can also be used by other REST clients to publish on behalf of this client. See the publishing over REST on behalf of a realtime client documentation for more info.

The recovery key String can be used by another client to recover this connection’s state in the recover client options property. See connection state recover options for more information.

The serial number Integer of the last message to be received on this connection, used automatically by the library when recovering or resuming a connection. When recovering a connection explicitly, the recoveryKey is used in the recover client options as it contains both the key and the last message serial.

connect()

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.

close()

Causes the connection to close, entering the closing state. Once closed, the library will not attempt to re-establish the connection without an explicit call to connect()“:#connect.

There are two overloaded versions of this method:

on(String state, listener(ConnectionStateChange stateChange))

Register the given listener for the specified ConnectionState state changes on the Connection. The listener is passed a ConnectionStateChange object that contains the current state, previous state, and an optional reason for the state change.</span>

on(listener(ConnectionStateChange stateChange))

Register the given listener for all ConnectionState changes on the Connection. The listener is passed a ConnectionStateChange object that contains the current state, previous state, and an optional reason for the state change.</span>

Parameters

state
the connection state to subscribe toType: String
listener
is a function of the form function(stateChange) to be notified for matching state changes

Example

Browser ConnectionState change example

There are two overloaded versions of this method:

once(String state, listener(ConnectionStateChange stateChange))

Register the given listener for a single occurrence of the specified ConnectionState state change on the Connection. Once the listener has been called, it is removed as a registered listener and will not be called again. The listener is passed a ConnectionStateChange object that contains the current state, previous state, and an optional reason for the state change.

once(listener(ConnectionStateChange stateChange))

Register the given listener for a single occurrence of any ConnectionState change on the Connection. Once the listener has been called, it is removed as a registered listener and will not be called again. The listener is passed a ConnectionStateChange object that contains the current state, previous state, and an optional reason for the state change.

Parameters

state
the connection state to subscribe toType: String
listener
is a function of the form function(stateChange) to be notified for a single occurrence of a matching state change

There are two overloaded versions of this method:

off(String state, listener)

Remove the given listener for the ConnectionState state.

off(listener)

Remove the given listener for all ConnectionState states.

Parameters

state
the connection state to unsubscribe fromType: String
listener
is the listener function to be removed

ping(callback(ErrorInfo err))

When connected, sends a heartbeat ping to the Ably server and executes the callback when a heartbeat ping request is echoed from the server. This can be useful for measuring true roundtrip latency to the connected Ably server.

A ConnectionStateChange is a type encapsulating state change information emitted by the Connection object. See Connection#on to register a listener for one or more events.

Properties

current
the new stateType: State String
previous
the previous state. (for the update event, this will be equal to the current state)Type: State String
event
the event that triggered this state changeType: ConnectionEvent
reason
an ErrorInfo containing any information relating to the transitionType: ErrorInfo
retryIn
Duration upon which the library will retry a connection where applicable, as millisecondsType: Integer