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 theRTCIceCandidateInit
dictionary.Note: For backward compatibility, the constructor also accepts as input a string containing the value of thecandidate
property instead of aRTCIceCandidateInit
object, since thecandidate
includes all of the information thatRTCIceCandidateInit
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 acandidate-attribute
as defined in RFC 5245. This string is empty (""
) if theRTCIceCandidate
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 thecandidate
a-line string. The permitted values are listed in theRTCIceComponent
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 multipleRTCIceTransport
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 typeRTCIceProtocol
. relatedAddress
Read only- If the candidate is derived from another candidate,
relatedAddress
is aDOMString
containing that host candidate's IP address. For host candidates, this value isnull
. 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, therelatedPort
property isnull
. 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, ornull
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
isnull
. type
Read only- A
DOMString
indicating the type of candidate as one of the strings from theRTCIceCandidateType
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 sameusernameFragment
, even across ICE restarts.
Methods
toJSON()
- Given the
RTCIceCandidate
's current configuration,toJSON()
returns aDOMString
containing a JSON representation of that configuration in the form of aRTCIceCandidateInit
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
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
RTCIceCandidate | Chrome Full support Yes | Edge Full support ≤18 | Firefox Full support 22 | IE No support No | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
RTCIceCandidate() constructor | Chrome Full support Yes | Edge Full support ≤18 | Firefox
Full support
22
| IE No support No | Opera Full support Yes | Safari ? | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android
Full support
Yes
| Opera Android Full support Yes | Safari iOS ? | Samsung Internet Android Full support Yes |
address | Chrome Full support 74 | Edge
Full support
79
| Firefox ? | IE No support No | Opera ? | Safari ? | WebView Android Full support 74 | Chrome Android Full support 74 | Firefox Android ? | Opera Android ? | Safari iOS ? | Samsung Internet Android Full support 11.0 |
candidate | Chrome Full support 23 | Edge Full support 15 | Firefox Full support 22 | IE No support No | Opera Full support 15 | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support 25 | Firefox Android Full support Yes | Opera Android Full support 14 | Safari iOS Full support Yes | Samsung Internet Android Full support 1.5 |
component | Chrome Full support 74 | Edge Full support ≤79 | Firefox No support No | IE No support No | Opera ? | Safari ? | WebView Android Full support 74 | Chrome Android Full support 74 | Firefox Android No support No | Opera Android ? | Safari iOS ? | Samsung Internet Android Full support 11.0 |
foundation | Chrome Full support 74 | Edge Full support ≤18 | Firefox No support No | IE No support No | Opera No support No | Safari ? | WebView Android Full support 74 | Chrome Android Full support 74 | Firefox Android ? | Opera Android No support No | Safari iOS ? | Samsung Internet Android Full support 11.0 |
port | Chrome Full support 74 | Edge Full support ≤18 | Firefox No support No | IE No support No | Opera No support No | Safari ? | WebView Android Full support 74 | Chrome Android Full support 74 | Firefox Android No support No | Opera Android No support No | Safari iOS ? | Samsung Internet Android Full support 11.0 |
priority | Chrome Full support 74 | Edge Full support ≤18 | Firefox No support No | IE No support No | Opera No support No | Safari ? | WebView Android Full support 74 | Chrome Android Full support 74 | Firefox Android No support No | Opera Android No support No | Safari iOS ? | Samsung Internet Android Full support 11.0 |
protocol | Chrome Full support 74 | Edge Full support ≤18 | Firefox No support No | IE No support No | Opera No support No | Safari ? | WebView Android Full support 74 | Chrome Android Full support 74 | Firefox Android No support No | Opera Android No support No | Safari iOS ? | Samsung Internet Android Full support 11.0 |
relatedAddress | Chrome Full support 74 | Edge Full support ≤18 | Firefox No support No | IE No support No | Opera No support No | Safari ? | WebView Android Full support 74 | Chrome Android Full support 74 | Firefox Android No support No | Opera Android No support No | Safari iOS ? | Samsung Internet Android Full support 11.0 |
relatedPort | Chrome Full support 74 | Edge Full support ≤18 | Firefox No support No | IE No support No | Opera No support No | Safari ? | WebView Android Full support 74 | Chrome Android Full support 74 | Firefox Android No support No | Opera Android No support No | Safari iOS ? | Samsung Internet Android Full support 11.0 |
sdpMid | Chrome Full support 23 | Edge Full support 15 | Firefox Full support 22 | IE No support No | Opera Full support 15 | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support 25 | Firefox Android Full support Yes | Opera Android Full support 14 | Safari iOS Full support Yes | Samsung Internet Android Full support 1.5 |
sdpMLineIndex | Chrome Full support 23 | Edge Full support 15 | Firefox Full support 22 | IE No support No | Opera Full support 15 | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support 25 | Firefox Android Full support Yes | Opera Android Full support 14 | Safari iOS Full support Yes | Samsung Internet Android Full support 1.5 |
tcpType | Chrome Full support 74 | Edge Full support ≤18 | Firefox No support No | IE No support No | Opera No support No | Safari ? | WebView Android Full support 74 | Chrome Android Full support 74 | Firefox Android No support No | Opera Android No support No | Safari iOS ? | Samsung Internet Android Full support 11.0 |
toJSON | Chrome Full support 45 | Edge Full support 15 | Firefox Full support 27 | IE No support No | Opera Full support 32 | Safari Full support Yes | WebView Android Full support 45 | Chrome Android Full support 45 | Firefox Android Full support 27 | Opera Android Full support 32 | Safari iOS Full support Yes | Samsung Internet Android Full support 5.0 |
type | Chrome Full support 74 | Edge Full support ≤18 | Firefox No support No | IE No support No | Opera No support No | Safari ? | WebView Android Full support 74 | Chrome Android Full support 74 | Firefox Android No support No | Opera Android No support No | Safari iOS ? | Samsung Internet Android Full support 11.0 |
usernameFragment | Chrome Full support 74 | Edge Full support ≤79 | Firefox Full support 67 | IE No support No | Opera ? | Safari ? | WebView Android Full support 74 | Chrome Android Full support 74 | Firefox Android Full support 67 | Opera Android ? | Safari iOS ? | Samsung Internet Android Full support 11.0 |
Legend
- Full support
- Full support
- No support
- No support
- Compatibility unknown
- Compatibility unknown
- See implementation notes.
- See implementation notes.
- Uses a non-standard name.
- Uses a non-standard name.