This is the third blog post in our REST API integration series. In the previous blog posts, we explained how to integrate signaling state changes and gathering state changes into our REST API. Today, we continue to address the ICE domain and take a closer look at ICE connection state changes.

Establishing Connectivity Between Peers Using ICE

In our previous blog post on gathering state changes, we explained how two peers, Alice and Bob, gather ICE candidates to use for establishing connectivity between each other.

Having gathered their respective ICE candidates, Alice and Bob complete the following steps:

1. They exchange their respective candidates with one another through an application server.
2. They create ICE candidate pairs by matching every local ICE candidate with every ICE candidate received from their peer.
3. They prioritize ICE candidate pairs in terms of the potential network latency they may offer. That is, host candidates are likely to have lower latency than relay candidates.

After those steps are completed, the ICE connectivity check phase starts. It is important to understand that for the ICE connectivity checks to start, the ICE candidates gathering phase does not need to be completed. This is called Trickle ICE, and all modern web browsers support this type of operation. The older systems that do not support Trickle ICE require that all ICE candidates are gathered before the ICE connectivity checks can start.

In the ICE connectivity checks, Alice takes the ICE candidate pair with the highest priority and sends a connectivity request packet in the format of STUN request from the pair local ICE candidate address to the pair remote ICE candidate address. She then waits a few milliseconds before taking the next ICE candidate pair from the priority list and repeats the process.

Bob, upon receiving the ICE connectivity request packet, sends an ICE connectivity response packet in the format of STUN response. If the response packet is received, the ICE connectivity check for that particular pair has succeeded.

Independently, Bob does the same thing as Alice but on his side.

The connectivity checks continue after finding the very first working ICE candidate pair until all ICE candidate pairs are checked or until one of the peers that plays the ICE controlling role decides to stop the process. The ICE connectivity checks are concluded by selecting, or nominating, the ICE candidate pair that is going to be used for communication by the ICE controlling peer. The ICE candidate pair is chosen from the pairs that successfully passed the connectivity checks.

Upon successful connectivity establishment, Alice and Bob must periodically continue sending keepalive messages to keep NAT bindings alive for the media session.

ICE Connection States in WebRTC

ICE connection states in WebRTC track the process of ICE connectivity checks and of managing connectivity between peers. To illustrate this process, let us examine how Alice’s ICE connection state changes as she tries to connect to Bob.

Alice starts in the new state when a new PeerConnection is created. When the list of ICE candidates is received from Bob and “installed” in the PeerConnection (pc.setRemoteDescription and pc.addIceCandidate), the WebRTC stack starts the ICE connectivity checks and checking state is reached. When the WebRTC stack finds the first ICE candidate pair that has successfully passed the ICE connectivity checks, connected state is reached. When the process of ICE connectivity checks is successfully finished, completed state is reached.

This transition of states is illustrated in Figure 1 below. The WebRTC stack continues to periodically send ICE keepalive messages as required per standard.

If some ICE keepalive message fails to succeed, disconnected state is reached. This state can be reached from both connected and completed states. If connectivity between peers is restored, the ICE connection state gets back to either connected or completed. However, if connectivity does not get restored within 30 seconds, failed state is reached. Figure 1 illustrates all possible transitions of the ICE connection state.

Figure 1: Transition of ICE Connectivity States

Proper integration of ICE connection state transitions is vital to enable callstats.io to properly diagnose potential ICE problems that can arise during the ICE connectivity checks and connectivity management during the call. It allows us to discover the following issues:

• Prolonged setup delay
• Potential reasons behind failures to establish connectivity
• Dropped connections

For step-by-step instruction on integrating the REST API, please have a look at our REST API documentation.

In the next blog post of this series, we will explain how to properly integrate the REST API with user media events. Stay tuned!