addIceCandidate

addIceCandidate is a method of the RTCPeerConnection interface in the WebRTC API. It is used to add a remote ICE candidate to the local peer connection so that the ICE agent can consider this candidate during connectivity checks. This process is part of ICE, which helps peers establish a path through NATs and firewalls for media and data streams.

Signature and return: In modern browsers, addIceCandidate accepts an RTCIceCandidate object or an RTCIceCandidateInit dictionary and returns a Promise that resolves when the candidate has been added or rejects if there is an error. Older browsers exposed a callback-based form with separate success and failure callbacks.

Usage and timing: ICE candidates are gathered by each peer and exchanged via a signaling channel. When a candidate is received from the remote peer, the application constructs the appropriate candidate object and calls addIceCandidate to incorporate it into the local RTCPeerConnection. Candidates are typically added after negotiation has begun, and you may need to handle candidates before or after the remote description is set depending on the implementation. The candidate data includes fields such as candidate, sdpMid, and sdpMLineIndex to locate the correct media description.

End-of-candidates and signaling notes: Some implementations support signaling of the end of candidate gathering, but this is not required. Applications should not rely on a specific end-of-candidates signal and should continue ICE discovery until the connection is established or ICE fails.

Compatibility and pitfalls: The Promise-based form is standard in modern engines (Chrome, Edge, Firefox, Safari). Some legacy code or older browsers may use the callback form or require additional checks for remote description state before calling addIceCandidate. Proper signaling and synchronization remain important for successful connectivity.