RTCPeerConnection.setConfiguration()

This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.

The RTCPeerConnection.setConfiguration() method sets the current configuration of the RTCPeerConnection based on the values included in the specified RTCConfiguration object. This lets you change the ICE servers used by the connection and which transport policies to use.

The most common use case for this method (and even then, probably not a very common use case) is to replace the set of ICE servers to be used. Two potential scenarios in which this might be done:

  • The RTCPeerConnection was instantiated without specifying any ICE servers. If, for example, the RTCPeerConnection() constructor was called with no parameters, you would have to then call setConfiguration() to add ICE servers before ICE negotiation could begin.
  • Renegotiation of the connection is needed, and a different set of ICE servers needs to be used for some reason. Perhaps the user has moved into a new region, so using new regional ICE servers is necessary, for example. In this situation, one might call setConfiguration() to switch to new regional ICE servers, then initiate an ICE restart.

You cannot change the identity information for a connection once it's already been set.

Syntax

RTCPeerConnection.setConfiguration(configuration);

Parameters

configuration
An RTCConfiguration object which provides the options to be set. The changes are not additive; instead, the new values completely replace the existing ones.

Exceptions

InvalidAccessError
One or more of the URLs specified in configuration.iceServers is a TURN server, but complete login information is not provided (that is, either the RTCIceServer.username or RTCIceServer.credentials is missing). This prevents successful login to the server.
InvalidModificationError
The configuration includes changed identity information, but the connection already has identity information specified. This happens if configuration.peerIdentity or configuration.certificates is set and their values differ from the current configuration.
InvalidStateError
The RTCPeerConnection is closed.
SyntaxError
One or more of the URLs provided in the configuration.iceServers list is invalid.

Example

In this example, it has already been determined that ICE restart is needed, and that negotiation needs to be done using a different ICE server.

var restartConfig = { iceServers: [{
                          urls: "turn:asia.myturnserver.net",
                          username: "allie@oopcode.com",
                          credential: "topsecretpassword"
                      }]
};
myPeerConnection.setConfiguration(restartConfig);
myPeerConnection.createOffer({"iceRestart": true}).then(function(offer) {
  return myPeerConnection.setLocalDescription(offer);
})
.then(function() {
  // send the offer to the other peer using the signaling server
})
.catch(reportError);

First, a new RTCConfiguration is created, restartConfig, specifying the new ICE server and its credentials. This is then passed into setConfiguration(). ICE negotiation is restarted by calling createOffer(), specifying true as the value of the iceRestart option. From there, we handle the process as usual, by setting the local description to the returned offer and then sending that offer to the other peer.

Specifications

Specification Status Comment
WebRTC 1.0: Real-time Communication Between Browsers
The definition of 'setConfiguration()' in that specification.
Working Draft Initial definition.

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 58[1] CompatNo ? 45 ?
Feature Android Webview Chrome for Android Firefox Mobile (Gecko) Firefox OS IE Mobile Opera Mobile Safari Mobile
Basic support 58[1] 58[1] CompatNo CompatNo ? 45 ?

[1] Though this method is not prefixed, the interface it belongs to was until Chrome 56.

See also

Document Tags and Contributors

 Contributors to this page: jpmedley, Sheppy
 Last updated by: jpmedley,