<img src="https://certify.alexametrics.com/atrk.gif?account=bIEZv1FYxz20cv" style="display:none" height="1" width="1" alt="">

Managing Connection States and Configuring Automatic Reconnections


Project Complexity: ★★★★☆

Relevant Languages: JavaScript/TypeScript and Node.js

When your application uses the High Fidelity Spatial Audio API, it makes a connection to the High Fidelity servers using the HiFiCommunicator class and its connectToHiFiAudioAPIServer() method. Your users will only be able to talk to each other while they are connected to High Fidelity servers. This guide explores the different ways in which your application can get information about the state of a user's connection, and explains how to manage reconnections due to failed connections either automatically or manually.

Info Icon

This guide goes into detail about the connection lifecycle and how to manage connections using the JavaScript Client Library. For more information about how to make a basic connection to a High Fidelity server, please refer to the "Build a Simple Web App" and "Get a JWT" guides.

The rest of this guide assumes that you are comfortable with creating and using HiFiCommunicator objects.


1. Getting the Current State of a Connection

The HiFiCommunicator class provides the method getConnectionState() to return the current state of a HiFiCommunicator object. The possible connection states are listed in the HiFiConnectionStates enumeration, and are summarized here:

  • Disconnected - the initial state of a HiFiCommunicator before it has been connected to the server, and the final state after the connection has been terminated.
  • Connecting - the state while the HiFiCommunicator is in the process of opening a connection to the server.
  • Connected - the state of a stable connection
  • Reconnecting - the state if the HiFiCommunicator is in the process of automatically reconnecting (see "Configuring Auto-Reconnects" below)
  • Disconnecting - the state when the connection is in the process of being manually disconnected through the use of the disconnectFromHiFiAudioAPIServer() method
  • Failed - a temporary state that indicates the connection has failed. This state will immediately transition automatically to "Disconnected."

At any time during a session, HiFiCommunicator.getConnectionState() can be called to determine the current state of the connection.


2. Life Cycle of a High Fidelity Connection

The following diagram illustrates the life cycle of a connection. Please note that the automatic retry behavior and the "Reconnecting" state will only be used if auto-reconnects are enabled (see "Configuring Auto-Reconnects" below).

(Click the image below to make it larger.)

Diagram describing SDK Connection Handling


Info Icon

By default, the HiFiCommunicator will NOT attempt to automatically reconnect dropped sessions or retry initial connection attempts! To enable the auto-reconnect feature, you MUST use the ConnectionRetryAndTimeoutConfig settings to enable and configure it.

3. Configuring Auto-Reconnects and Other Connection Parameters

When constructing a HiFiCommunicator object, you can specify a connectionRetryAndTimeoutConfig parameter that will define how the HiFiCommunicator should handle the situation where an initial connection attempt fails, or when an existing connection is inadvertently disconnected (e.g. due to a network disruption).

Alert Icon

Warning: Automatic reconnection of an existing connection does NOT currently take into account what caused the connection to fail. It will therefore attempt to reconnect ALL connections, including connections that were terminated due to an administrator issuing the "Kick" command to remove a user from a space.

For the moment, High Fidelity does NOT recommend enabling the autoRetryOnDisconnect capability if you rely on the "Kick" functionality to remove bad actors. (This will likely change in the future; watch our release notes for updates!)

The format of the connectionRetryAndTimeoutConfig parameter is specified by the ConnectionRetryAndTimeoutConfig interface, defined inside the HiFiCommunicator class. There are several different settings that can be used to enable and configure the automatic reconnection attempts. Retries for the initial connection attempt can be configured separately from retries for disconnected connections.

The most important properties of a ConnectionRetryAndTimeoutConfig object are the booleans autoRetryInitialConnection and autoRetryOnDisconnect. To enable basic, default auto-reconnection capabilities, set both of these to true when creating a HiFiCommunicator object. With these set to true, the initial attempt to connect will retry for 15 seconds, and any subsequent disconnects after the first connection will retry for 60 seconds (1 minute). Here is an example of a HiFiCommunicator that has been configured to use the default auto-reconnect behavior:

If the defaults are not suitable for your application, you can directly configure the amount of time spent trying to reconnect either initial connections or disconnected sessions. For instance, you may not want to attempt to retry failed connections for a full minute, but rather to provide the user with an alternate course of action after only 30 seconds. In this situation, you can include either or both of the maxSecondsToSpendRetryingInitialConnection or maxSecondsToSpendRetryingOnDisconnect properties in your connectionRetryAndTimeoutConfig object, like so:

Finally, the connectionRetryAndTimeoutConfig interface provides two additional configuration parameters that can be useful for configuring connections:

  • pauseBetweenRetriesMS configures the amount of time to wait in between retries. A higher value for this property will allow more time to pass between attempts to retry (both initial connections and reconnects of dropped sessions). This can be useful if you want to allow more time for the user's network connection to recover before attempting each reconnect. This defaults to 500ms, and can not be set lower than 100ms.
  • timeoutPerConnectionAttemptMS configures the amount of time to wait before timing out a specific individual connection attempt (for instance, in the case of a slow network or a problem with domain name resolution). This defaults to 5000ms, or 5 seconds. In certain situations where a user is physically located very far away from the High Fidelity servers (which are primarily located on the West Coast of the United States), it may be necessary to increase this value in order to give the client and the server time to establish a connection with each other.


4. Using a Connection State Change Handler

Another way to monitor and manage connections is through the use of a connection state change event handler. This connection state change handler allows you to provide your own function that will get called each time the state of the connection changes.

Info Icon

When you specify a connection state change handler, the function you provide will be called for every change to the connection state, including transient or informational states like "Connecting" or "Failed". Please refer to the "Life Cycle" diagram above for details about the different states, and design your handler to take action only for those states that are relevant to your application. Remember that the "Failed" state is transitory and will automatically trigger a disconnection, causing the state to then transition to "Disconnected."

When the HiFiCommunicator state changes, it will trigger a call to your custom state change handler, with the new HiFiConnectionState passed as the first parameter to the handler. Additionally, a "message" object that conforms to the HiFiCommunicator.HiFiConnectionAttemptResult interface will be passed as the second parameter. This object will always contain a success boolean indicating whether or not the state change was due to a successful transition (e.g. a state change from "Connecting" to "Connected"), as well as an optional error string containing errors or other informational messages. Additionally, the HiFiConnectionAttemptResult interface contains an optional audionetInitResponse object when the new state is "Connected." This audionetInitResponse object is primarily used for debugging, and contains general information about the High Fidelity server to which the HiFiCommunicator is connected.

To provide a connection state change handler, specify the name of your function when constructing your HiFiCommunciator, by setting the onConnectionStateChanged parameter. For example: 


A connection state change handler can be used to provide feedback to the user, or to take action when different states occur. For instance, if you would prefer finer-grained control over reconnection behavior, you could use a connection state handler to implement your own reconnection logic and disable the High Fidelity auto-reconnect capability. Or, if you are using the auto-reconnect capability, you can also use a state change handler in order to provide notifications to your users when reconnects are attempted.

Info Icon

You can use a state change handler regardless of whether or not you are using High Fidelity's automatic reconnection capability. However, if you are using High Fidelity's auto-reconnect feature, we recommend that your state change handler not attempt to affect the connection (for instance, by attempting to reconnect failed connections), because it could conflict with the auto-reconnect behavior.

Please refer to the connection life cycle diagram and the documentation for the HiFiConnectionStates enumeration for more details about the different states that a typical connection will encounter.
Info Icon

HiFiCommunicator sessions will always attempt to fully disconnect if a connection is interrupted. Therefore, a "Failure" state is transitory and you do not need to explicitly tell the HiFiCommunicator to disconnect when you receive this notification. A session that has been disconnected inadvertently will have its state changed to "Failure," but the state will then immediately proceed to "Disconnected." This ensures that all connections are completely disconnected if a failure occurs. If you are implementing custom reconnection logic through the use of state change handlers, we recommend that you do not attempt a new connection until the final "Disconnected" state is reached, to avoid attempting to reconnect a session that is still in the process of disconnecting.


5. Using Connection and Disconnection Promises

One final way in which your application interacts with the connection state of the HiFiCommunicator is through the JavaScript Promises that are returned by the methods HiFiCommunicator.connectToHiFiAudioAPIServer() and HiFiCommunicator.disconnectFromHiFiAudioAPIServer(). When invoked, each of these two methods will immediately return a Promise, and the Promise will either resolve or reject once the attempt to connect or disconnect has completed.

When your application uses the auto-retry capability for initial connection attempts described in the "Configuring Auto-Reconnects" section above, the Promise that is returned from the connectToHiFiAudioAPIServer() method will only resolve or reject once all retry attempts have completed. If the final state of the session is "Connected," the Promise will resolve; if all attempts to connect have failed and the final state of the session is "Disconnected," the Promise will reject. 

Note that these Promises are only relevant when your application code explicitly calls the HiFiCommunicator.connectToHiFiAudioAPIServer() or HiFiCommunicator.disconnectFromHiFiAudioAPIServer() methods, and so you may want to use them in combination with a state change handler. These Promises will be updated at the same time as the state changes, and will match the observed connection state of the HiFiCommunicator. Specifically, if the Promise has rejected, the state of the HiFiCommunicator will have gone to "Failed" and then to "Disconnected." if the Promise has resolved, the state will be at "Connected."


6. Summary

In this guide, you learned how to inspect and react to changes in the connection state of a High Fidelity audio session. You also learned how to configure and use the High Fidelity auto-reconnect capabilities.

For detailed technical information about the High Fidelity Spatial Audio Client API, visit the API documentation.

If you have any questions or comments, please reach out to support@highfidelity.com.