RTCIceServers.urls

Draft
This page is not complete.

I'm experimenting with structure for pages documenting members of dictionaries. Please contact sheppy with any feedback.

This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The RTCIceServer dictionary's urls property specifies the URL or URLs of the servers to be used for ICE negotiations. These are typically STUN and/or TURN servers.

Syntax

var iceServer = {
                  urls = iceServerUrl | [ url1, ..., urlN ],
                  username: "webrtc", // optional
                  credential: "turnpassword" // optional
                };

iceServers.push(iceServer);

The value of this property may be specified as a single URL or as an array of multiple URLs.

Examples

Let's look a few examples of varying complexity.

A single ICE server

This example creates a new RTCPeerConnection which will use a STUN server at stunserver.example.org to negotiate connections.

myPeerConnection = new RTCPeerConnection({
  iceServers: [
    {
      urls: "stun:stunserver.example.org"
    }
  ]
});

Notice that only the urls property is provided; the STUN server doesn't require authentication, so this is all that's needed.

A single ICE server with authentication

The second example creates a new RTCPeerConnection which will use a TURN server at turnserver.example.org to negotiate connections. Logging into the TURN server will use the username "webrtc" and the creative password "turnpassword".

myPeerConnection = new RTCPeerConnection({
  iceServers: [
    {
      urls: "turn:turnserver.example.org",
      username: "webrtc",
      credential: "turnpassword"
    }
  ]
});

A single ICE server with multiple URLs

The next example creates a new RTCPeerConnection which will use a single TURN server which has multiple URLs. This is useful if the server is, for example, available both on "turn" and "turns" schemes, or if there's a fallback address available for the server.

Keep in mind that ICE will try all the URLs you list here, so the more you include, the longer connections will take to establish.

myPeerConnection = new RTCPeerConnection({
  iceServers: [
    {
      urls: ["turns:turnserver.example.org", "turn:turnserver.example.org"],
      username: "webrtc",
      credential: "turnpassword"
    }
  ]
});

Multiple ICE servers

Finally, this example creates a new RTCPeerConnection which will use one of two servers for ICE negotiation. Each server can have one or more URLs, as demonstrated above.

myPeerConnection = new RTCPeerConnection({
  iceServers: [
    {
      urls: ["turns:turnserver.example.org", "turn:turnserver.example.org"],
      username: "webrtc",
      credential: "turnpassword"
    },
    {
      urls: "stun: stunserver.example.org"
    }
  ]
});

Two ICE servers are provided. One is a TURN server which can be accessed both over TURN and TURNS. The other is a STUN server. Any number of servers could be listed of any combination of types.

Specifications

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

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
Basic supportChrome Full support YesEdge ? Firefox Full support 37IE ? Opera ? Safari ? WebView Android No support NoChrome Android Full support YesEdge Mobile ? Firefox Android Full support 37Opera Android ? Safari iOS ? Samsung Internet Android Full support Yes

Legend

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

See also

Document Tags and Contributors

Contributors to this page: betimer, fscholz, Sheppy
Last updated by: betimer,