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

<p><span class="seoSummary"> <code>RTCPeerConnection</code> 속성의 <strong>{{domxref("RTCPeerConnection.onicecandidate", "onicecandidate")}}</strong> 는 {{domxref("RTCPeerConnection")}} 인스턴스에서 {{event("icecandidate")}} 이벤트 발생시에 호출 하려는 함수를 지정합니다. 이 이벤트는 로컬 {{Glossary("ICE")}} 에이전트가 signaling 서버를 통해 원격 피어에게 메세지를 전달 할 필요가 있을때 마다 발생합니다. 그리고 ICE 에이전트가 signaling에 사용되는 기술에 대한 구체사항을 모르더라도 원격 피어와의 네고시에이션을 수행하도록 도와줍니다. 어떤 메세징 기술을 선택하던간에, 이 메소드를 사용해서 원격 피어에 ICE candidate를 전달하는 과정을 간단하게 구현 할 수 있습니다.</span> </p>

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

<pre class="syntaxbox"><em>RTCPeerConnection</em>.onicecandidate = <em>eventHandler</em>;
</pre>

<h3 id="값">값</h3>

<p><code>onicecandidate </code>속성은 {{event("icecandidate")}} 이벤트를 나타내는 {{domxref("RTCPeerConnectionIceEvent")}} 객체를 입력 값으로 받는 함수로 설정되어야합니다. 여기에 설정되는 함수는 ICE candidate를 signaling 서버를 통해 원격 피어에게 전달해야합니다. 이때, ICE candidate의 {{Glossary("SDP")}}는 이벤트의 {{domxref("RTCPeerConnectionIceEvent.candidate", "candidate")}} 속성에서 확인 할 수 있습니다. 만약 이벤트의 <code>candidate </code>속성이 <code>null</code>로 지정되어있다면, ICE 수집과정이 완료됩니다. 이 메세지는 원격 피어에 전달되지 않아야합니다. 이때, 연결의 {{domxref("RTCPeerConnection.iceGatheringState", "iceGatheringState")}} 또한 <code>complete</code>로 바뀌게 됩니다. ICE 수집 상태를 명시적으로 감시할 필요는 없습니다. 다만, signaling의 종료를 감지해야 한다면, ICE 네고시에이션이 complete 상태로 변한것을 알려주는 {{domxref("RTCPeerConnection.icegatheringstatechange_event", "icegatheringstatechange")}} 이벤트를 감시하면 됩니다.</p>

<h2 id="예시">예시</h2>

<p>아래는 <a href="/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling">Signaling and video calling</a> 문서의 코드를 기반으로 원격 피어에게 ICE candidate를 전달하는 {{event("icecandidate")}} 이벤트에 대한 핸들러를 설정합니다.</p>

<pre class="brush: js">pc.onicecandidate = function(event) {
  if (event.candidate) {
    // event.candidate가 존재하면 원격 유저에게 candidate를 전달합니다.
  } else {
    // 모든 ICE candidate가 원격 유저에게 전달된 조건에서 실행됩니다.
    // candidate = null
  }
}</pre>

<p>위에서 알 수 있듯이, 이벤트의 {{domxref("RTCPeerConnectionIceEvent.candidate", "candidate")}} 속성이 <code>null</code>이면 네고시에이션의 종료가 감지됩니다. </p>

<h2 id="명세">명세</h2>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">명세</th>
   <th scope="col">상태</th>
   <th scope="col">코멘트</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{ SpecName('WebRTC 1.0', '#widl-RTCPeerConnection-onicecandidate', 'RTCPeerConnection.onicecandidate') }}</td>
   <td>{{ Spec2('WebRTC 1.0') }}</td>
   <td>Initial specification.</td>
  </tr>
 </tbody>
</table>

<h2 id="브라우저_호환성">브라우저 호환성</h2>



<p>{{Compat("api.RTCPeerConnection.onicecandidate")}}</p>

<h2 id="참조">참조</h2>

<ul>
 <li>{{event("icecandidate")}} 이벤트 및 이벤트의 타입인 {{domxref("RTCPeerConnectionIceEvent")}}.</li>
</ul>