This article needs a technical review. How you can help.
This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.
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 the new candidate to the RTCPeerConnection
's remote description, which describes the state of the remote end of the connection.
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
RTCIceCandidate
orRTCIceCandidateInit
object which has been constructed from a message received over the signaling channel and is 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.
Example
This code snippet shows how to construct a candidate object from a string which contains SDP describing a candidate. This string previously arrived over the signaling channel.
// |receivedSDP| is an SDP string received over the signaling channel // by our handler for "new ICE candidate" messages. let candidate = new RTCIceCandidate(receivedSDP); pc.addIceCandidate(candidate).then({ // Do stuff when the candidate is successfully passed to the ICE agent }).catch({ console.log("Error: Failure during addIceCandidate()"); });
Specifications
Specification | Status | Comment |
---|---|---|
WebRTC 1.0: Real-time Communication Between Browser The definition of 'RTCPeerConnection.addIceCandidate()' in that specification. |
Working Draft | Initial specification. |
WebRTC 1.0: Real-time Communication Between Browser The definition of 'RTCPeerConnection.addIceCandidate()' in that specification. |
Working Draft | Initial specification. |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | (Yes) [1] | 22 (22) [1] | No support | (Yes) | ? |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | ? | ? | 22.0 (22) | No support | ? | ? |
[1] Though this property is not prefixed, the interface it belongs to was until Firefox 44.