Revision 1047128 of RTCConfiguration

<p>{{APIRef("WebRTC")}}{{draft}}</p>

<p>The <strong><code>RTCConfiguration</code></strong> dictionary is used to provide configuration options for an {{domxref("RTCPeerConnection")}}. It may be passed into the constructor when instantiating a connection, or used with the {{domxref("RTCPeerConnection.getConfiguration()")}} and {{domxref("RTCPeerConnection.setConfiguration()")}} methods, which allow inspecting and changing the configuration while a connection is established.</p>

<p>The options include ICE server and transport settings and identity information.</p>

<h2 id="Properties">Properties</h2>

<dl>
 <dt><code>bundlePolicy</code> {{optional_inline}}</dt>
 <dd>Specifies how to handle negotiation of candidates when the remote peer is not compatible with the <a href="https://webrtcstandards.info/sdp-bundle/">SDP BUNDLE standard</a>. This must be one of the values from the enum <code><a href="#RTCBundlePolicy_enum">RTCBundlePolicy</a></code>. If this value isn't included in the dictionary, <code>"balanced"</code> is assumed.</dd>
 <dt><code>certificates</code> {{optional_inline}}</dt>
 <dd>An {{jsxref("Array")}} of objects of type {{domxref("RTCCertificate")}} which are used by the connection for authentication. If this property isn't specified, a set of certificates is generated automatically for each {{domxref("RTCConnection")}} instance. See {{anch("Using certificates")}} below for additional information.
 <div class="note">This configuration option cannot be changed after it is first specified; once the certificates have been set, this property is ignored in future calls to {{domxref("RTCPeerConnection.setConfiguration()")}}.</div>
 </dd>
 <dt><code>iceCandidatePoolSize</code> {{optional_inline}}</dt>
 <dd>An unsigned 16-bit integer value which specifies the size of the prefetched ICE pool. The default value is 0 (meaning no candidate prefetching will occur). You may find in some cases that connections can be established more quickly by allowing the ICE agent to start fetching ICE candidates before you start trying to connect, so that they're already available for inspection when {{domxref("RTCPeerConnection.setLocalDescription()")}} is called.</dd>
 <dt><code>iceServers</code> {{optional_inline}}</dt>
 <dd>An array of {{domxref("RTCIceServer")}} objects, each describing one server which may be used by the ICE agent; these are typically STUN and/or TURN servers.</dd>
 <dt><code>iceTransportPolicy</code> {{optional_inline}}</dt>
 <dd>The current ICE transport policy; this must be one of the values from the <code><a href="#RTCIceTransportPolicy_enum">RTCIceTransportPolicy</a></code> enum. If this isn't specified, <code>"all"</code> is assumed.</dd>
 <dt><code>peerIdentity</code> {{optional_inline}}</dt>
 <dd>A {{domxref("DOMString")}} which specifies the target peer identity for the {{domxref("RTCPeerConnection")}}. If this value is set (it defaults to <code>null</code>), the <code>RTCPeerConnection</code> will not connect to a remote peer unless it can successfully authenticate with the given name.</dd>
 <dt><code>rtcpMuxPolicy</code> {{optional_inline}}</dt>
 <dd>The RTCP mux policy to use when gathering ICE candidates. The value must be one of those from the <a href="#RTCRtcpMuxPolicy_enum"><code>RTCRtcpMuxPolicy</code> enum</a>. The default is <code>"require"</code>.</dd>
</dl>

<h3 id="RTCIceServer_Properties">RTCIceServer Properties</h3>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Name</th>
   <th scope="col">Type</th>
   <th scope="col">Description</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><code>urls</code></td>
   <td>{{domxref("DOMString")}}, {{jsxref("Array")}}</td>
   <td>Either a string specifying a single STUN or TURN server's URI to use, or an array of strings specifying multiple URIs for servers with multiple addresses.</td>
  </tr>
  <tr>
   <td><code>username</code></td>
   <td>{{domxref("DOMString")}}</td>
   <td>An account username (optional)</td>
  </tr>
  <tr>
   <td><code>credential</code></td>
   <td>{{domxref("DOMString")}}</td>
   <td>The password associated with username, if given (optional)</td>
  </tr>
 </tbody>
</table>

<p>Avoid specifying an unnecessarily large number of URLs in the <code>urls</code> property; the startup time for your connection will go up substantially. Every server in the list will be contacted and tried out before one is selected to be used for negotiation.</p>

<div class="note">
<p>Older versions of the WebRTC specification included an <code>url</code> property instead of <code>urls</code>; this was changed in order to let you specify multiple addresses for each server in the list, as shown in the example below.</p>
</div>

<h2 id="Constants">Constants</h2>

<p>{{page("/en-US/docs/Web/API/RTCPeerConnection", "RTCBundlePolicy enum", 0, 1)}}</p>

<p>{{page("/en-US/docs/Web/API/RTCPeerConnection", "RTCIceTransportPolicy enum", 0, 1)}}</p>

<p>{{page("/en-US/docs/Web/API/RTCPeerConnection", RTCRtcpMuxPolicy enum", 0, 1)}}</p>

<h2>Using certificates</h2>

<p>When you wish to provide your own certificates for use by an {{domxref("RTCPeerConnection")}} instead of having the <code>RTCPeerConnection</code> generate them automatically, you do so through calls to {{domxref("RTCPeerConnection.generateCertificate()")}}.</p>

<p>This attribute supports providing multiple certificates because even though a given DTLS connection uses only one certificate, providing multiple certificates allows support for multiple encryption algorithms. The implementation of <code>RTCPeerConnection</code> will choose which certificate to use based on the algorithms it and the remote peer support, as determined during DTLS handshake.</p>

<p>If you don't provide certificates, new ones are generated automatically. One obvious benefit to providing your own is identity key continuity—if you use the same certificate for subsequent calls, the remote peer can tell you're the same caller. This also avoids the cost of generating new keys.</p>

<p>&lt;&lt;&lt;link to added info on identity&gt;&gt;&gt;</p>

<h2 id="Example">Example</h2>

<pre class="brush: js">
var configuration = { iceServers: [{
                          urls: "stun:stun.services.mozilla.com",
                          username: "[email protected]", 
                          credential: "webrtcdemo"
                      }, {
                          urls: ["stun:stun.example.com", "stun:stun-1.example.com"]
                      }]
};

var pc = new RTCPeerConnection(configuration);</pre>