RTCPeerConnection.addIceCandidate()

When a web site or app using RTCPeerConnection receives a new ICE candidate from the remote peer over its signaling channel, it delivers the newly-received candidate to the browser's ICE agent by calling RTCPeerConnection.addIceCandidate(). This adds this new remote candidate to the RTCPeerConnection's remote description, which describes the state of the remote end of the connection.

If the value of the specified object's candidate is an empty string (""), it signals that all remote candidates have been delivered (end-of-candidates).

During negotiation, your app will likely receive many candidates which you'll deliver to the ICE agent in this way, allowing it to build up a list of potential connection methods. This is covered in more detail in the articles WebRTC connectivity and Signaling and video calling.

Syntax

aPromise = pc.addIceCandidate(candidate);

addIceCandidate(candidate, successCallback, failureCallback);  

Parameters

candidate
An object conforming to the RTCIceCandidateInit dictionary; the contents of the object should be constructed from a message received over the signaling channel, describing a newly received ICE candidate that's ready to be delivered to the local ICE agent.

Deprecated parameters

In older code and documentation, you may see a callback-based version of this function. This has been deprecated and its use is strongly discouraged. You should update any existing code to use the Promise-based version of addIceCandidate() instead. The parameters for this form of addIceCandidate() are described below, to aid in updating existing code.

successCallback
A function to be called when the ICE candidate has been successfully added. This function receives no input parameters and doesn't return a value.
failureCallback
A function to be called if attempting to add the ICE candidate fails. Receives as input a DOMException object describing why failure occurred.

Return value

A Promise which is fulfilled when the candidate has been successfully added to the remote peer's description by the ICE agent. The promise does not receive any input parameters.

Exceptions

When an error occurs while attempting to add the ICE candidate, the Promise returned by this method is rejected, returning one of the errors below as the name attribute in the specified DOMException object passed to the rejection handler.

TypeError
The specified candidate's sdpMid and sdpMLineIndex are both null.
InvalidStateError
The RTCPeerConnection currently has no remote peer established (remoteDescription is null).
OperationError
This can happen for a number of reasons:
  • The value specified for sdpMid is non-null and doesn't match the media description ID of any media description included within the remoteDescription.
  • The specified value of sdpMLineIndex is greater than or equal to the number of media descriptions included in the remote description.
  • The specified ufrag doesn't match the ufrag field in any of the remote descriptions being considered.
  • One or more of the values in the candidate string are invalid or could not be parsed.
  • Attempting to add the candidate fails for any reason. 

Examples

This code snippet shows how to signal ICE candidates across an arbitrary signaling channel.

// This example assumes that the other peer is using a signaling channel as follows:
//
// pc.onicecandidate = event => {
//   if (event.candidate) {
//     signalingChannel.send(JSON.stringify({ice: event.candidate})); // "ice" is arbitrary
//   } else {
//     // All ICE candidates have been sent
//   }
// }

signalingChannel.onmessage = receivedString => {
  const message = JSON.parse(receivedString);
  if (message.ice) {
    // A typical value of ice here might look something like this:
    //
    // {candidate: "candidate:0 1 UDP 2122154243 192.168.1.9 53421 typ host", sdpMid: "0", ...}
    //
    // Pass the whole thing to addIceCandidate:

    pc.addIceCandidate(message.ice).catch(e => {
      console.log("Failure during addIceCandidate(): " + e.name);
    });
  } else {
    // handle other things you might be signaling, like sdp
  }
}

The last candidate to be signaled this way by the remote peer will be a special candidate denoting end-of-candidates. Out of interest, end-of-candidates may be manually indicated as follows:

pc.addIceCandidate({candidate:''});

Specifications

Specification Status Comment
WebRTC 1.0: Real-time Communication Between Browsers
The definition of 'RTCPeerConnection.addIceCandidate()' in that specification.
Candidate Recommendation Initial specification.
WebRTC 1.0: Real-time Communication Between Browsers
The definition of 'RTCPeerConnection.addIceCandidate()' in that specification.
Candidate Recommendation Initial specification.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidiOS SafariSamsung Internet
Basic support
Experimental
Chrome Full support 56
Notes
Full support 56
Notes
Notes Promise based version and unprefixed.
No support 50 — 56
Notes
Notes Promise based version.
Edge Full support 15Firefox Full support 22IE ? Opera Full support 43
Notes
Full support 43
Notes
Notes Promise based version.
No support 37 — 43
Safari ? WebView Android Full support 56
Notes
Full support 56
Notes
Notes Promise based version and unprefixed.
No support 50 — 56
Notes
Notes Promise based version.
Chrome Android Full support 56
Notes
Full support 56
Notes
Notes Promise based version and unprefixed.
No support 50 — 56
Notes
Notes Promise based version.
Edge Mobile Full support YesFirefox Android Full support 44Opera Android Full support 43
Notes
Full support 43
Notes
Notes Promise based version.
No support 37 — 43
Safari iOS ? Samsung Internet Android Full support 6.0
Notes
Full support 6.0
Notes
Notes Promise based version and unprefixed.
No support 5.0 — 6.0
Notes
Notes Promise based version.

Legend

Full support  
Full support
Compatibility unknown  
Compatibility unknown
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.
See implementation notes.
See implementation notes.

See also

Document Tags and Contributors

Contributors to this page: Jib, boldt, Sheppy, fscholz, jpmedley, abbycar, cauburtin, rolfedh
Last updated by: Jib,