Understanding WebRTC iceConnectionState

This article explains the purpose of the WebRTC iceConnectionState attribute and what its various states communicate to the application layer. By understanding these states, developers can effectively monitor, troubleshoot, and manage the lifecycle of a peer-to-peer connection.

The iceConnectionState attribute, part of the RTCPeerConnection interface, indicates the current state of the Interactive Connectivity Establishment (ICE) agent. It informs the application layer about the viability, quality, and status of the connection between the local user and the remote peer. The application layer uses this information to update user interfaces (such as displaying “Connecting…” or “Disconnected” banners) and to trigger recovery mechanisms like ICE restarts.

The attribute can have one of the following string values, each signaling a specific condition to the application:

• new: The ICE agent is waiting for remote candidates to be added or for gathering to begin. The connection is in its initial setup phase.
• checking: The ICE agent has received remote candidates and is actively pairing them with local candidates to find a viable connection path. It is sending connectivity checks.
• connected: A usable pair of local and remote candidates has been found, and a connection is established. Media and data can now flow between the peers. However, the ICE agent may still be checking other candidate pairs for a better path.
• completed: The ICE agent has finished testing all candidate pairs and has settled on the best connection path. Gathering and checking are finished.
• failed: The ICE agent has finished checking all candidate pairs and failed to find a compatible connection path. This usually signals to the application layer that it should trigger an ICE restart or inform the user that the connection cannot be established.
• disconnected: At least one active component of the connection has failed a keep-alive check. This is often a transient state caused by temporary network disruptions. The connection can recover on its own or transition to failed.
• closed: The RTCPeerConnection instance has been shut down, and the ICE agent is no longer active.

By listening to the iceconnectionstatechange event, the application layer can dynamically react to these transitions, ensuring a seamless and resilient user experience during network changes or dropouts.