RTCPeerConnection.iceConnectionState — Eigenschaft · JavaScript-Referenz

Signatur

RTCPeerConnection.iceConnectionState

Beschreibung

Die Eigenschaft iceConnectionState zeigt an, wie weit der ICE-Agent (Interactive Connectivity Establishment) einer RTCPeerConnection mit dem Aufbau der Transportverbindung zum Gegenüber ist. Der ICE-Agent sammelt Kandidaten (Host, STUN, TURN), prüft Kandidatenpaare und wählt eine funktionierende Route aus. Der Wert ist einer der folgenden Strings:

"new": Der ICE-Agent sammelt Kandidaten oder wartet auf entfernte Kandidaten.
"checking": Kandidatenpaare werden geprüft, es wurde aber noch keine Verbindung gefunden.
"connected": Ein nutzbares Kandidatenpaar wurde gefunden, die Prüfung weiterer Paare kann noch laufen.
"completed": Die Prüfung ist abgeschlossen und für alle Komponenten wurde eine Verbindung gefunden.
"failed": Für mindestens eine Komponente wurde kein funktionierendes Paar gefunden. Ein ICE-Neustart ist nötig.
"disconnected": Die Konnektivitätsprüfung ist für mindestens eine Komponente fehlgeschlagen. Das ist oft nur vorübergehend (z. B. bei einem Netzwerkwechsel) und kann sich selbst beheben.
"closed": Der ICE-Agent wurde beendet, weil close() aufgerufen wurde.

Jede Änderung löst das Ereignis iceconnectionstatechange aus. Man verwendet die Eigenschaft vor allem, um Verbindungsabbrüche zu erkennen, die Nutzeroberfläche anzupassen (z. B. mit „Verbinde…“ oder „Verbindung verloren“) und bei "failed" gezielt einen ICE-Neustart über restartIce() anzustoßen.

Wer den Gesamtzustand der Verbindung wissen will, einschließlich DTLS, sollte zusätzlich oder stattdessen connectionState auswerten. iceConnectionState beschreibt nur die ICE-Transportebene.

Rückgabewert

Typ

Beschreibung

Ein String, der den aktuellen ICE-Verbindungszustand angibt. Die Eigenschaft ist schreibgeschützt.

Beispiele

Aktuellen Zustand direkt nach dem Erstellen abfragen

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

console.log(pc.iceConnectionState);

pc.close();
console.log(pc.iceConnectionState);

new closed

Zustandswechsel mit addEventListener überwachen und die Oberfläche aktualisieren

const pc = new RTCPeerConnection();
const statusEl = document.querySelector('#status');

const labels = {
  new: 'Initialisiere…',
  checking: 'Verbinde…',
  connected: 'Verbunden',
  completed: 'Verbunden',
  disconnected: 'Verbindung unterbrochen – warte…',
  failed: 'Verbindung fehlgeschlagen',
  closed: 'Beendet'
};

const onIceStateChange = () => {
  const state = pc.iceConnectionState;
  console.log('ICE-Zustand:', state);
  statusEl.textContent = labels[state] ?? state;
};

pc.addEventListener('iceconnectionstatechange', onIceStateChange);

// Später, z. B. beim Aufräumen:
// pc.removeEventListener('iceconnectionstatechange', onIceStateChange);

ICE-Zustand: checking ICE-Zustand: connected

Automatischer ICE-Neustart bei "failed" und Zeitlimit bei "disconnected"

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

let disconnectTimer = null;

// Neuverhandlung: Das neue Angebot enthält frische ICE-Zugangsdaten
pc.onnegotiationneeded = async () => {
  const offer = await pc.createOffer();
  await pc.setLocalDescription(offer);
  // signaling.send({ sdp: pc.localDescription });
};

pc.oniceconnectionstatechange = () => {
  switch (pc.iceConnectionState) {
    case 'disconnected':
      // Oft nur vorübergehend: kurz abwarten
      disconnectTimer = setTimeout(() => {
        if (pc.iceConnectionState === 'disconnected') {
          console.warn('Weiterhin getrennt – starte ICE neu');
          pc.restartIce();
        }
      }, 5000);
      break;
    case 'failed':
      console.warn('ICE fehlgeschlagen – starte ICE neu');
      pc.restartIce();
      break;
    case 'connected':
    case 'completed':
      clearTimeout(disconnectTimer);
      break;
  }
};

// Wichtig · Fallstricke

„disconnected“ ist nicht endgültig: Der Zustand tritt oft bei kurzen Netzwerkstörungen auf, etwa beim Wechsel zwischen WLAN und Mobilfunk, und geht häufig von selbst wieder in "connected" über. Trennen Sie die Verbindung also nicht sofort, sondern warten Sie eine Weile.
„failed“ braucht einen Neustart: Aus diesem Zustand erholt sich die Verbindung nicht von selbst. Rufen Sie restartIce() auf und verhandeln Sie neu. In älteren Browsern geht das mit createOffer({ iceRestart: true }).
„completed“ ist nicht garantiert: Manche Browser (z. B. Chrome bei Trickle-ICE) melden nie "completed". Behandeln Sie "connected" und "completed" deshalb gleich.
connectionState ist oft die bessere Wahl: Diese Eigenschaft fasst ICE- und DTLS-Zustand zusammen und ist für die Anzeige in der Oberfläche meist aussagekräftiger. Firefox unterstützt connectionState erst seit Version 113. Ältere Safari-Versionen setzten nur iceConnectionState um.
Nach close() wird kein iceconnectionstatechange-Ereignis mehr für "closed" ausgelöst. Den Wert müssen Sie also selbst abfragen.
Die Eigenschaft ist schreibgeschützt. Wenn Sie ihr etwas zuweisen, wird das still ignoriert, im Strict Mode gibt es einen TypeError.

Siehe auch

RTCPeerConnection RTCPeerConnection.connectionState RTCPeerConnection.iceGatheringState RTCPeerConnection.prototype.restartIce() RTCPeerConnection.signalingState PerformanceTiming.secureConnectionStart