RTCIceCandidate

The RTCIceCandidate interface—part of the WebRTC API—represents a candidate Internet Connectivity Establishment (ICE) configuration which may be used to establish an RTCPeerConnection.

An ICE candidate describes the protocols and routing needed for WebRTC to be able to communicate with a remote device. When starting a WebRTC peer connection, typically a number of candidates are proposed by each end of the connection, until they mutually agree upon one which describes the connection they decide will be best. WebRTC then uses that candidate's details to initiate the connection.

For details on how the ICE process works, see Lifetime of a WebRTC session. The article WebRTC connectivity provides additional useful details.

Constructor

RTCIceCandidate()
Creates an RTCIceCandidate object to represent a single ICE candidate, optionally configured based on an object based on the RTCIceCandidateInit dictionary.
Note: For backward compatibility, the constructor also accepts as input a string containing the value of the candidate property instead of a RTCIceCandidateInit object, since the candidate includes all of the information that RTCIceCandidateInit does and more.

Properties

candidate Read only
A DOMString representing the transport address for the candidate that can be used for connectivity checks. The format of this address is a candidate-attribute as defined in RFC 5245. This string is empty ("") if the RTCIceCandidate is an "end of candidates" indicator.
component Read only
A DOMString which indicates whether the candidate is an RTP or an RTCP candidate; its value is either "rtp" or "rtcp", and is derived from the  "component-id" field in the candidate a-line string. The permitted values are listed in the RTCIceComponent enumerated type.
foundation Read only
Returns a DOMString containing a unique identifier that is the same for any candidates of the same type, share the same base (the address from which the ICE agent sent the candidate), and come from the same STUN server. This is used to help optimize ICE performance while prioritizing and correlating candidates that appear on multiple RTCIceTransport objects.
ip Read only
A DOMString containing the IP address of the candidate.
port Read only
An integer value indicating the candidate's port number.
priority Read only
A long integer value indicating the candidate's priority.
protocol Read only
A string indicating whether the candidate's protocol is "tcp" or "udp". The string is one of those in the enumerated type RTCIceProtocol.
relatedAddress Read only
If the candidate is derived from another candidate, relatedAddress is a DOMString containing that host candidate's IP address. For host candidates, this value is null.
relatedPort Read only
For a candidate that is derived from another, such as a relay or reflexive candidate, the relatedPort is a number indicating the port number of the candidate from which this candidate is derived. For host candidates, the relatedPort property is null.
sdpMid Read only
A DOMString specifying the candidate's media stream identification tag which uniquely identifies the media stream within the component with which the candidate is associated, or null if no such association exists.
sdpMLineIndex Read only
If not null, sdpMLineIndex indicates the zero-based index number of the media description (as defined in RFC 4566) in the SDP with which the candidate is associated.
tcpType Read only
If protocol is "tcp"tcpType represents the type of TCP candidate. Otherwise, tcpType is null.
type Read only
A DOMString indicating the type of candidate as one of the strings from the RTCIceCandidateType enumerated type.
usernameFragment Read only
A DOMString containing a randomly-generated username fragment ("ice-ufrag") which ICE uses for message integrity along with a randomly-generated password ("ice-pwd"). You can use this string to verify generations of ICE generation; each generation of the same ICE process will use the same usernameFragment, even across ICE restarts.

Methods

toJSON()
Given the RTCIceCandidate's current configuration, toJSON() returns a DOMString containing a JSON representation of that configuration in the form of a RTCIceCandidateInit object.

Examples

For examples, see the article Signaling and video calling, which demonstrates the entire process.

Specifications

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

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidiOS SafariSamsung Internet
Basic supportChrome Full support YesEdge Full support YesFirefox Full support 22IE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android ? Opera Android Full support YesSafari iOS ? Samsung Internet Android Full support Yes
RTCIceCandidate()Chrome Full support YesEdge Full support YesFirefox Full support 22IE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android ? Opera Android Full support YesSafari iOS ? Samsung Internet Android Full support Yes
candidateChrome Full support YesEdge Full support 15Firefox Full support 22IE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android ? Opera Android Full support YesSafari iOS ? Samsung Internet Android Full support Yes
foundationChrome No support NoEdge Full support YesFirefox No support NoIE No support NoOpera No support NoSafari ? WebView Android No support NoChrome Android No support NoEdge Mobile Full support YesFirefox Android ? Opera Android No support NoSafari iOS ? Samsung Internet Android Full support Yes
ipChrome No support NoEdge Full support YesFirefox No support NoIE No support NoOpera No support NoSafari ? WebView Android No support NoChrome Android No support NoEdge Mobile Full support YesFirefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support Yes
portChrome No support NoEdge Full support YesFirefox No support NoIE No support NoOpera No support NoSafari ? WebView Android No support NoChrome Android No support NoEdge Mobile Full support YesFirefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support Yes
priorityChrome No support NoEdge Full support YesFirefox No support NoIE No support NoOpera No support NoSafari ? WebView Android No support NoChrome Android No support NoEdge Mobile Full support YesFirefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support Yes
protocolChrome No support NoEdge Full support YesFirefox No support NoIE No support NoOpera No support NoSafari ? WebView Android No support NoChrome Android No support NoEdge Mobile Full support YesFirefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support Yes
relatedAddressChrome No support NoEdge Full support YesFirefox No support NoIE No support NoOpera No support NoSafari ? WebView Android No support NoChrome Android No support NoEdge Mobile Full support YesFirefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support Yes
relatedPortChrome No support NoEdge Full support YesFirefox No support NoIE No support NoOpera No support NoSafari ? WebView Android No support NoChrome Android No support NoEdge Mobile Full support YesFirefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support Yes
sdpMidChrome Full support YesEdge Full support 15Firefox Full support 22IE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android ? Opera Android Full support YesSafari iOS ? Samsung Internet Android Full support Yes
sdpMLineIndexChrome Full support YesEdge Full support 15Firefox Full support 22IE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android ? Opera Android Full support YesSafari iOS ? Samsung Internet Android Full support Yes
tcpTypeChrome No support NoEdge Full support YesFirefox No support NoIE No support NoOpera No support NoSafari ? WebView Android No support NoChrome Android No support NoEdge Mobile Full support YesFirefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support Yes
typeChrome No support NoEdge Full support YesFirefox No support NoIE No support NoOpera No support NoSafari ? WebView Android No support NoChrome Android No support NoEdge Mobile Full support YesFirefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support Yes
componentChrome No support NoEdge ? Firefox No support NoIE No support NoOpera ? Safari ? WebView Android No support NoChrome Android No support NoEdge Mobile ? Firefox Android No support NoOpera Android ? Safari iOS ? Samsung Internet Android ?
usernameFragmentChrome ? Edge ? Firefox No support NoIE ? Opera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android No support NoOpera Android ? Safari iOS ? Samsung Internet Android ?
toJSONChrome ? Edge Full support 15Firefox Full support 27IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android Full support 27Opera Android ? Safari iOS ? Samsung Internet Android ?

Legend

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

Document Tags and Contributors

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