RTCPeerConnection: icegatheringstatechange event

BaselineWidely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2017.

Theicegatheringstatechange event is sent to theonicegatheringstatechange event handler on anRTCPeerConnection when the state of theICE candidate gathering process changes.This signifies that the value of the connection'siceGatheringState property has changed.

When ICE first starts to gather connection candidates, the value changes fromnew togathering to indicate that the process of collecting candidate configurations for the connection has begun. When the value changes tocomplete, all of the transports that make up theRTCPeerConnection have finished gathering ICE candidates.

Note:While you can determine that ICE candidate gathering is complete by watching foricegatheringstatechange events and checking for the value oficeGatheringState to becomecomplete, you can also have your handler for theicecandidate event look to see if itscandidate property isnull. This also indicates that collection of candidates is finished.

This event is not cancelable and does not bubble.

Syntax

Use the event name in methods likeaddEventListener(), or set an event handler property.

addEventListener("icegatheringstatechange", (event) => { })onicegatheringstatechange = (event) => { }

Event type

A genericEvent.

Examples

This example creates a handler foricegatheringstatechange events.

pc.onicegatheringstatechange = (ev) => {  let connection = ev.target;  switch (connection.iceGatheringState) {    case "gathering":      /* collection of candidates has begun */      break;    case "complete":      /* collection of candidates is finished */      break;  }};

Likewise, you can useaddEventListener() to add a listener foricegatheringstatechange events:

pc.addEventListener(  "icegatheringstatechange",  (ev) => {    let connection = ev.target;    switch (connection.iceGatheringState) {      case "gathering":        // collection of candidates has begun        break;      case "complete":        // collection of candidates is finished        break;    }  },  false,);