RTCPeerConnection: iceconnectionstatechange — Ereignis · JavaScript-Referenz

Signatur

peerConnection.addEventListener("iceconnectionstatechange", handler)

Beschreibung

Das Ereignis iceconnectionstatechange wird bei einer RTCPeerConnection jedes Mal ausgelöst, wenn sich der Wert der Eigenschaft iceConnectionState ändert. ICE (Interactive Connectivity Establishment) ist das Verfahren, mit dem WebRTC einen funktionierenden Netzwerkpfad zwischen zwei Gegenstellen sucht, zum Beispiel direkt, über STUN oder über ein TURN-Relay.

Mögliche Zustände sind "new", "checking", "connected", "completed", "disconnected", "failed" und "closed". Das Ereignis selbst ist ein einfaches Event ohne zusätzliche Daten. Den neuen Zustand liest man im Handler aus pc.iceConnectionState aus.

Typische Einsatzfälle sind Statusanzeigen in der Oberfläche („Verbinde…“, „Verbunden“, „Verbindung unterbrochen“), die Erkennung von Netzwerkproblemen und das Anstoßen eines ICE-Neustarts mit pc.restartIce(), wenn der Zustand "failed" erreicht wird.

Den Handler registriert man entweder mit addEventListener("iceconnectionstatechange", handler) oder über die Eigenschaft pc.oniceconnectionstatechange = handler. Soll nur der Gesamtzustand der Verbindung (ICE und DTLS zusammen) überwacht werden, ist oft connectionstatechange die bessere Wahl.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"iceconnectionstatechange"`.
$handler Pflicht	(event: Event) => void		Callback-Funktion. Sie erhält ein einfaches `Event`. Den neuen Zustand liest man aus `event.target.iceConnectionState` aus.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal`, um den Listener mit einem `AbortController` zu entfernen.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück.

Beispiele

Verbindungsstatus mit addEventListener anzeigen

const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
});

const labels = {
  new: 'Bereit',
  checking: 'Verbinde…',
  connected: 'Verbunden',
  completed: 'Verbunden (optimaler Pfad)',
  disconnected: 'Verbindung unterbrochen',
  failed: 'Verbindung fehlgeschlagen',
  closed: 'Geschlossen'
};

pc.addEventListener('iceconnectionstatechange', () => {
  console.log('ICE-Status:', pc.iceConnectionState, '→', labels[pc.iceConnectionState]);
});

// Kanal anlegen, damit ICE-Aushandlung startet
pc.createDataChannel('chat');
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

ICE-Status: checking → Verbinde… ICE-Status: connected → Verbunden

ICE-Neustart bei Fehler über die on-Property

const pc = new RTCPeerConnection();

pc.oniceconnectionstatechange = async () => {
  if (pc.iceConnectionState === 'failed') {
    console.warn('ICE fehlgeschlagen – starte Neuaushandlung');
    // setzt beim nächsten Offer iceRestart automatisch
    pc.restartIce();
  }
};

// restartIce() löst negotiationneeded aus
pc.onnegotiationneeded = async () => {
  await pc.setLocalDescription();
  // signaling.send({ description: pc.localDescription });
};

ICE fehlgeschlagen – starte Neuaushandlung

Kurze Unterbrechung abwarten, Listener sauber entfernen

const pc = new RTCPeerConnection();
const controller = new AbortController();
let disconnectTimer = null;

const onIceChange = () => {
  const state = pc.iceConnectionState;
  clearTimeout(disconnectTimer);

  if (state === 'disconnected') {
    // disconnected ist oft nur vorübergehend (z. B. WLAN-Wechsel)
    disconnectTimer = setTimeout(() => {
      console.log('Unterbrechung dauert an – Nutzer informieren');
    }, 5000);
  }

  if (state === 'closed') {
    controller.abort(); // Listener entfernen
  }
};

pc.addEventListener('iceconnectionstatechange', onIceChange, {
  signal: controller.signal
});

// Alternative ohne AbortController:
// pc.removeEventListener('iceconnectionstatechange', onIceChange);

// Wichtig · Fallstricke

Kein Ereignis bei close(): Ruft man pc.close() auf, wechselt iceConnectionState zwar auf "closed", das Ereignis wird laut Spezifikation aber nicht ausgelöst. Aufräumarbeiten gehören deshalb direkt neben den Aufruf von close().
"disconnected" ist oft nur vorübergehend: Bei kurzen Netzwerkaussetzern kehrt der Zustand häufig von selbst auf "connected" zurück. Reagieren Sie erst nach einer Wartezeit oder bei "failed".
"completed" wird nicht von allen Browsern gemeldet. Chrome meldet diesen Zustand zum Beispiel für den steuernden Agenten, Firefox und Safari melden oft nur "connected". Prüfen Sie deshalb beide Werte.
Für den Gesamtzustand (ICE plus DTLS) sind connectionState und connectionstatechange zuverlässiger. Firefox unterstützt connectionstatechange erst seit Version 113.
restartIce() gibt es in allen aktuellen Browsern. In älteren Umgebungen nutzt man stattdessen createOffer({ iceRestart: true }).
Der Handler erhält ein einfaches Event ohne Zustandsdaten. Lesen Sie den Zustand immer aus der Verbindung selbst aus.

Siehe auch

RTCPeerConnection RTCPeerConnection.iceConnectionState connectionstatechange icegatheringstatechange icecandidate RTCPeerConnection.prototype.restartIce() PaymentRequest: shippingaddresschange