RTCPeerConnection: connectionstatechange — Ereignis · JavaScript-Referenz

Signatur

peerConnection.addEventListener("connectionstatechange", handler)

Beschreibung

Das Ereignis connectionstatechange wird an einer RTCPeerConnection ausgelöst, wenn sich der Wert von RTCPeerConnection.connectionState ändert. Man registriert es entweder mit addEventListener("connectionstatechange", handler) oder über die Eigenschaft onconnectionstatechange. Das Ereignis ist ein einfaches Event ohne zusätzliche Daten. Es steigt nicht auf (bubbling) und lässt sich nicht abbrechen. Den neuen Zustand liest man im Handler direkt aus pc.connectionState aus.

connectionState fasst die Zustände aller ICE- und DTLS-Transporte der Verbindung zusammen. Mögliche Werte sind "new", "connecting", "connected", "disconnected", "failed" und "closed". Deshalb eignet sich dieses Ereignis besser für die Anzeige in der Oberfläche und die Fehlerbehandlung als iceconnectionstatechange, das nur die ICE-Ebene betrachtet.

Typische Einsätze:

den Status „Verbinde…“, „Verbunden“ oder „Verbindung verloren“ anzeigen,
bei "failed" einen ICE-Neustart mit pc.restartIce() auslösen,
bei "disconnected" eine Zeit lang warten, ob sich die Verbindung von selbst erholt,
Ressourcen wie Medien-Tracks und Timer aufräumen, wenn die Verbindung endgültig beendet ist.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"connectionstatechange"`.
$handler Pflicht	(event: Event) => void		Callback-Funktion. Sie erhält ein einfaches `Event`. Den neuen Zustand liefert `event.target.connectionState` bzw. `pc.connectionState`.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once` oder `signal`, zum Beispiel ein `AbortSignal`, um den Listener gezielt wieder zu entfernen.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Rückgabewert des Handlers wird ignoriert.

Beispiele

Verbindungsstatus in der Oberfläche anzeigen

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

const labels = {
  new: 'Bereit',
  connecting: 'Verbinde …',
  connected: 'Verbunden',
  disconnected: 'Verbindung unterbrochen',
  failed: 'Verbindung fehlgeschlagen',
  closed: 'Beendet'
};

pc.addEventListener('connectionstatechange', () => {
  console.log('Neuer Zustand:', pc.connectionState);
  document.querySelector('#status').textContent = labels[pc.connectionState];
});

Neuer Zustand: connecting Neuer Zustand: connected

Automatischer ICE-Neustart bei Fehlern

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

pc.onconnectionstatechange = () => {
  switch (pc.connectionState) {
    case 'disconnected':
      // Kurz warten – oft erholt sich die Verbindung von selbst
      disconnectTimer = setTimeout(() => {
        if (pc.connectionState === 'disconnected') pc.restartIce();
      }, 5000);
      break;
    case 'failed':
      console.warn('Verbindung fehlgeschlagen – starte ICE neu');
      pc.restartIce(); // löst negotiationneeded aus
      break;
    case 'connected':
      clearTimeout(disconnectTimer);
      break;
  }
};

Verbindung fehlgeschlagen – starte ICE neu

Listener mit AbortController wieder entfernen

const pc = new RTCPeerConnection();
const controller = new AbortController();

pc.addEventListener('connectionstatechange', () => {
  if (pc.connectionState === 'connected') {
    console.log('Erstverbindung steht – Listener wird entfernt');
    controller.abort();
  }
}, { signal: controller.signal });

// Alternative ohne Signal:
// const onChange = () => { /* ... */ };
// pc.addEventListener('connectionstatechange', onChange);
// pc.removeEventListener('connectionstatechange', onChange);
// bzw. pc.onconnectionstatechange = null;

Erstverbindung steht – Listener wird entfernt

// Wichtig · Fallstricke

Kein Ereignis bei close(): Ruft man pc.close() selbst auf, springt connectionState auf "closed", ohne dass connectionstatechange ausgelöst wird. Aufräumarbeiten sollten daher zusätzlich direkt nach dem close()-Aufruf erfolgen.
"disconnected" ist oft nur vorübergehend, zum Beispiel bei einem Wechsel von WLAN zu Mobilfunk. Nicht sofort abbrechen, sondern eine Wartezeit einplanen. Erst "failed" bedeutet, dass die Verbindung ohne ICE-Neustart nicht zurückkommt.
Browser-Kompatibilität: Firefox unterstützt connectionState und dieses Ereignis erst ab Version 113. Für ältere Browser kann man als Rückfallebene iceconnectionstatechange mit iceConnectionState verwenden.
Die frühere MDN-Formulierung, das Ereignis hänge mit neuen Tracks an einem RTCRtpReceiver zusammen, ist irreführend. Für neue Tracks ist das Ereignis track zuständig.
Das Ereignis enthält keine Zustandsdaten. Den Zustand immer aus pc.connectionState lesen.

Siehe auch

RTCPeerConnection RTCPeerConnection.connectionState RTCPeerConnection: iceconnectionstatechange RTCPeerConnection.prototype.restartIce() RTCPeerConnection: track RTCPeerConnection.prototype.close() NetworkInformation: change