This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
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:
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.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.
RTCPeerConnection.setConfiguration(configuration);
configuration
RTCConfiguration
object which provides the options to be set. The changes are not additive; instead, the new values completely replace the existing ones.InvalidAccessError
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
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
RTCPeerConnection
is closed.SyntaxError
configuration.iceServers
list is invalid.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: "[email protected]", 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.
Specification | Status | Comment |
---|---|---|
WebRTC 1.0: Real-time Communication Between Browsers The definition of 'setConfiguration()' in that specification. | Candidate Recommendation | Initial definition. |
Desktop | ||||||
---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | |
Basic support | 56 | Yes | 22 | ? | 43
|
? |
Mobile | |||||||
---|---|---|---|---|---|---|---|
Android webview | Chrome for Android | Edge Mobile | Firefox for Android | Opera for Android | iOS Safari | Samsung Internet | |
Basic support | 56 | 56 | Yes | 44 | 43
|
? | 6.0 |
© 2005–2018 Mozilla Developer Network and individual contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/setConfiguration