Web/API/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.

address Read only

The address of the candidate.

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 BrowsersThe definition of 'RTCIceCandidate' in that specification.	Candidate Recommendation	Initial definition.

Browser compatibility

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.

Update compatibility data on GitHub

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
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 Notes' Full support 22 Notes' Notes' Before Firefox 68, the constructor's options parameter was required.	IE No support No	Opera Full support Yes	Safari ?	WebView Android Full support Yes	Chrome Android Full support Yes	Firefox Android Full support Yes Notes' Full support Yes Notes' Notes' Before Firefox 68, the constructor's options parameter was required.	Opera Android Full support Yes	Safari iOS ?	Samsung Internet Android Full support Yes
address	Chrome Full support 74	Edge Full support 79 Full support 79 No support ≤18 — 79 Alternate Name' Alternate Name' Uses the non-standard name: ip	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.

RTCIceCandidate by Mozilla Contributors is licensed under CC-BY-SA 2.5.