---
title: RTCPeerConnection.addIceCandidate()
slug: Web/API/RTCPeerConnection/addIceCandidate
translation_of: Web/API/RTCPeerConnection/addIceCandidate
---
<p>{{APIRef("WebRTC")}}{{SeeCompatTable}}</p>

<p><span class="seoSummary">当本机当前页面的 {{domxref("RTCPeerConnection")}} 接收到一个从远端页面通过信号通道发来的新的 ICE 候选地址信息，本机可以通过调用<code><strong>RTCPeerConnection.addIceCandidate()</strong></code> 来添加一个 {{Glossary("ICE")}} 代理。</span> This adds this new remote candidate to the <code>RTCPeerConnection</code>'s remote description, which describes the state of the remote end of the connection.</p>

<p>If the value of the specified object'<code>s</code> {{domxref("RTCIceCandidate.candidate", "candidate")}} is an empty string (<code>""</code>), it signals that all remote candidates have been delivered.</p>

<p>During negotiation, your app will likely receive many candidates which you'll deliver to the ICE agent in this way, allowing it to build up a list of potential connection methods. This is covered in more detail in the articles <a href="/en-US/docs/Web/API/WebRTC_API/Connectivity">WebRTC connectivity</a> and <a href="/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling">Signaling and video calling</a>.</p>

<h2 id="Syntax">Syntax</h2>

<pre class="syntaxbox"><em>aPromise </em>= <em>pc</em>.addIceCandidate(<em>candidate</em>);

addIceCandidate(<em>candidate</em>, <em>successCallback</em>, <em>failureCallback</em>); {{deprecated_inline}}
</pre>

<h3 id="Parameters">Parameters</h3>

<dl>
 <dt><code>candidate</code></dt>
 <dd>An object conforming to the {{domxref("RTCIceCandidateInit")}} dictionary; the contents of the object should be constructed from a message received over the signaling channel, describing a newly received ICE candidate that's ready to be delivered to the local ICE agent.</dd>
</dl>

<h3 id="Deprecated_parameters">Deprecated parameters</h3>

<p>在一些老旧的代码和文档中, 你可能会看到一个回调函数(callback)版本的函数。这种函数是过期的，强烈建议不要使用。你应该更新你的代码，使用 {{jsxref("Promise")}}-版本的 <code>addIceCandidate()</code> . 这个版本的参数格式附在下面, 方便你更新已有的代码.</p>

<dl>
 <dt><code>successCallback</code> {{deprecated_inline}}</dt>
 <dd>A function to be called when the ICE candidate has been successfully added. This function receives no input parameters and doesn't return a value.</dd>
 <dt><code>failureCallback</code> {{deprecated_inline}}</dt>
 <dd>A function to be called if attempting to add the ICE candidate fails. Receives as input a {{domxref("DOMException")}} object describing why failure occurred.</dd>
</dl>

<h3 id="Return_value">Return value</h3>

<p>A {{jsxref("Promise")}} which is fulfilled when the candidate has been successfully added to the remote peer's description by the ICE agent. The promise does not receive any input parameters.</p>

<h3 id="Exceptions">Exceptions</h3>

<p>When an error occurs while attempting to add the ICE candidate, the {{jsxref("Promise")}} returned by this method is rejected, returning one of the errors below as the {{domxref("DOMException.name", "name")}} attribute in the specified {{domxref("DOMException")}} object passed to the rejection handler.</p>

<dl>
 <dt><code>TypeError</code></dt>
 <dd>The specified candidate doesn't have values for both {{domxref("RTCIceCandidate.sdpMid", "sdpMid")}} and {{domxref("RTCIceCandidate.sdpMLineIndex", "sdpMLineIndex")}}.</dd>
 <dt><code>InvalidStateError</code></dt>
 <dd>The <code>RTCPeerConnection</code> currently has no remote peer established ({{domxref("RTCPeerConnection.remoteDescription", "remoteDescription")}} is <code>null</code>).</dd>
 <dt><code>OperationError</code></dt>
 <dd>A non-<code>null</code> value was specified for {{domxref("RTCIceCandidate.sdpMid", "sdpMid")}}, but the value doesn't match the mid of any media description in the <code>remoteDescription</code>, or {{domxref("RTCIceCandidate.sdpMLineIndex", "sdpMLineIndex")}} is greater than or equal to the number of media descriptions in <code>remoteDescription</code>. This error can also be thrown if a value is given for {{domxref("RTCIceCandidate.ufrag", "ufrag")}} that doesn't match the value of <code>ufrag</code> in any of the remote description being selected.<br>
 <br>
 <code>OperationError</code> also occurs if the attempt to add the candidate fails for any other reason.</dd>
</dl>

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

<p>下段代码会展示如何使用一个SDP字符串(这个字符串包含了候选的描述)去构建一个候选对象。这个字符串来自于信道(signaling channel)。</p>

<pre class="brush: js">// |receivedSDP| is an SDP string received over the signaling channel
// by our handler for "new ICE candidate" messages.

let candidate = new RTCIceCandidate(receivedSDP);

pc.addIceCandidate(candidate).then(_=&gt;{
  // Do stuff when the candidate is successfully passed to the ICE agent
}).catch(e=&gt;{
  console.log("Error: Failure during addIceCandidate()");
});</pre>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{ SpecName('WebRTC 1.0', '#widl-RTCPeerConnection-addIceCandidate-Promise-void--RTCIceCandidateInit-RTCIceCandidate-candidate', 'RTCPeerConnection.addIceCandidate()') }}</td>
   <td>{{ Spec2('WebRTC 1.0') }}</td>
   <td>Initial specification.</td>
  </tr>
  <tr>
   <td>{{SpecName("WebRTC 1.0", "#widl-RTCPeerConnection-addIceCandidate-void-RTCIceCandidateInit-RTCIceCandidate-candidate-VoidFunction-successCallback-RTCPeerConnectionErrorCallback-failureCallback", "RTCPeerConnection.addIceCandidate()")}} {{deprecated_inline}}</td>
   <td>{{Spec2("WebRTC 1.0")}}</td>
   <td>Initial specification.</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<p>{{ CompatibilityTable}}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Edge</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{ CompatVersionUnknown}}[1]</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{ CompatGeckoDesktop(22) }} [2]</td>
   <td>{{ CompatNo}}</td>
   <td>{{ CompatVersionUnknown}}</td>
   <td>{{ CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Promise-based version</td>
   <td>{{CompatChrome(50)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{ CompatGeckoDesktop(37)}}</td>
   <td>{{ CompatUnknown}}</td>
   <td>{{ CompatUnknown}}</td>
   <td>{{ CompatUnknown}}</td>
  </tr>
  <tr>
   <td>{{domxref("RTCIceCandidateInit")}} as input</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoDesktop(53)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android Webview</th>
   <th>Chrome for Android</th>
   <th>Edge</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE Mobile</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{ CompatVersionUnknown}}[1]</td>
   <td>{{ CompatVersionUnknown}}[1]</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{ CompatGeckoMobile(22)}}</td>
   <td>{{ CompatNo}}</td>
   <td>{{ CompatUnknown}}</td>
   <td>{{ CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Promise-based version</td>
   <td>{{CompatChrome(50)}}</td>
   <td>{{CompatChrome(50)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(37)}}</td>
   <td>{{ CompatUnknown}}</td>
   <td>{{ CompatUnknown}}</td>
   <td>{{ CompatUnknown}}</td>
  </tr>
  <tr>
   <td>{{domxref("RTCIceCandidateInit")}} as input</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(53)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

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

<p>[2] Though this method is not prefixed, the interface it belongs to was until Firefox 44.</p>

<h2 id="See_also">See also</h2>

<ul>
 <li><a href="/en-US/docs/Web/API/WebRTC_API">WebRTC API</a></li>
 <li><a href="/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling">Signaling and video calling</a></li>
 <li><a href="/en-US/docs/Web/API/WebRTC_API/Architecture">WebRTC architecture overview</a></li>
 <li><a href="/en-US/docs/Web/API/WebRTC_API/Connectivity">WebRTC connectivity</a></li>
 <li><a href="/en-US/docs/Web/API/WebRTC_API/Session_lifetime">Lifetime of a WebRTC session</a></li>
</ul>