RTCPeerConnection: icecandidate event

An icecandidate event is sent to an RTCPeerConnection  when an RTCIceCandidate has been added to the target as a result of calling RTCPeerConnection.setLocalDescription(). This event handler should transmit the candidate to the remote peer so that the remote peer can add it its set of remote candidates.

Bubbles No
Cancelable No
Interface RTCPeerConnectionIceEvent
Event handler property RTCPeerConnection.onicecandidate

Usage notes

The icecandidate event, of type RTCPeerIceCandidateEvent, is sent for three reasons.

Sharing a new candidate

The primary reason an icecandidate event is sent is to indicate that a new candidate has been gathered, and it needs to be signaled to the remote peer, which will in turn add the candidate to its candidate pool by calling addIceCandidate(), passing in the candidate string you have passed along using the signaling server.

rtcPeerConnection.onicecandidate = (event) => {
  if (event.candidate) {
    sendCandidateToRemotePeer(event.candidate)
  }
}

Indicating the end of a generation of candidates

When an ICE negotiation session runs out of candidates to propose for a given RTCIceTransport, it has completed gathering for a generation of candidates. That this has occurred is indicated by an icecandidate event whose candidate string is empty ("").

You should deliver this to the remote peer just like any standard candidate, as described under Sharing a new candidate above. This ensures that the remote peer is given the end-of-candidates notification as well.

The end-of-candidates indication is described in section 9.3 of the Trickle ICE draft specification (note that the section number is subject to change as the specification goes through repeated drafts).

Indicating that ICE gathering is complete

Once all ICE transports have finished gathering candidates and the value of the RTCPeerConnection object's iceGatheringState has made the transition to complete, an icecandidate event is sent with the value of complete set to null.

This signal exists for backward compatibility purposes and does not need to be delivered onward to the remote peer (which is why the code snippet above checks to see if event.candidate is null prior to sending the candidate along.

Examples

This example creates a simple handler for the icecandidate event that uses a function called sendMessage() to create and send a reply to the remote peer through the signaling server.

First, an example using addEventListener():

pc.addEventListener("icecandidate", ev => {
  if (ev.candidate) {
    sendMessage({
      type: "new-ice-candidate",
      candidate: event.candidate
    });
  }
}, false);

You can also set the onicecandidate event handler property directly:

pc.onicecandidate = ev => {
  if (ev.candidate) {
    sendMessage({
      type: "new-ice-candidate",
      candidate: event.candidate
    });
  }
};

Specifications

Specification Status Comment
WebRTC 1.0: Real-time Communication Between Browsers
The definition of 'icecandidate' in that specification.
Candidate Recommendation

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
icecandidate eventChrome Full support 24Edge Full support 15Firefox Full support 22IE No support NoOpera Full support 43Safari Full support 11WebView Android Full support YesChrome Android Full support 25Firefox Android Full support 44Opera Android Full support 43Safari iOS ? Samsung Internet Android Full support 6.0

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown

See also

Document Tags and Contributors

Contributors to this page: Sheppy, mdnwebdocs-bot, fscholz, betimer, prestomation, erikadoyle, teoli
Last updated by: Sheppy,