RTCTransportStats.iceState — Eigenschaft · JavaScript-Referenz

Signatur

RTCTransportStats.iceState

Beschreibung

Die Eigenschaft iceState gehört zum Wörterbuch RTCTransportStats. Solche Objekte liefert RTCPeerConnection.getStats() in einem RTCStatsReport, und zwar mit type === "transport". Der Wert gibt den Zustand des ICE-Transports an, über den die Pakete dieser Verbindung laufen. Er entspricht RTCIceTransport.state.

Mögliche Werte sind "new", "checking", "connected", "completed", "disconnected", "failed" und "closed". Anders als RTCPeerConnection.iceConnectionState, das den Zustand aller Transporte zusammenfasst, bezieht sich iceState auf einen einzelnen Transport. Das ist nützlich, wenn kein Bundling verwendet wird und es deshalb mehrere Transporte gibt.

Typische Einsatzfälle sind Überwachungs-Dashboards, das Protokollieren der Verbindungsqualität und die Fehlersuche. Man kann iceState zum Beispiel zusammen mit selectedCandidatePairId, bytesSent/bytesReceived und dtlsState in regelmäßigen Abständen auslesen. So lässt sich erkennen, wann eine Verbindung abreißt oder ein ICE-Neustart nötig wird.

Rückgabewert

Typ

Beschreibung

Der ICE-Zustand des Transports als String (Aufzählungstyp RTCIceTransportState). Ist undefined, wenn der Browser das Feld nicht liefert.

Beispiele

ICE-Zustand aus dem Statistikbericht lesen

const pc = new RTCPeerConnection();
pc.createDataChannel('test');
await pc.setLocalDescription(await pc.createOffer());

const report = await pc.getStats();
report.forEach((stats) => {
  if (stats.type === 'transport') {
    console.log(`Transport ${stats.id}: ICE-Zustand = ${stats.iceState}`);
  }
});

Transport T01: ICE-Zustand = new

Verbindung überwachen und bei Fehler einen ICE-Neustart auslösen

const watchTransport = (pc, intervalMs = 2000) => {
  const timer = setInterval(async () => {
    const report = await pc.getStats();
    for (const stats of report.values()) {
      if (stats.type !== 'transport') continue;

      const { iceState, dtlsState, bytesReceived } = stats;
      console.log({ iceState, dtlsState, bytesReceived });

      if (iceState === 'failed') {
        console.warn('ICE fehlgeschlagen – starte ICE neu');
        pc.restartIce();
      }
    }
    if (pc.connectionState === 'closed') clearInterval(timer);
  }, intervalMs);
  return () => clearInterval(timer);
};

// Verwendung: const stop = watchTransport(peerConnection);

{ iceState: 'connected', dtlsState: 'connected', bytesReceived: 48213 }

Mit Fallback, falls iceState fehlt

const getIceState = async (pc) => {
  const report = await pc.getStats();
  const transport = [...report.values()].find((s) => s.type === 'transport');
  // Fallback auf den zusammengefassten Zustand der PeerConnection
  return transport?.iceState ?? pc.iceConnectionState;
};

const pc = new RTCPeerConnection();
console.log(await getIceState(pc));

new

// Wichtig · Fallstricke

Browserunterstützung: iceState kam erst später in die Spezifikation und wird nicht von allen Browsern bzw. Versionen geliefert. Deshalb sollte man immer mit undefined rechnen und auf RTCPeerConnection.iceConnectionState oder RTCIceTransport.state zurückfallen.
Momentaufnahme: Der Wert zeigt den Zustand nur zum Zeitpunkt des Aufrufs von getStats(). Um sofort auf Zustandswechsel zu reagieren, ist das Ereignis iceconnectionstatechange bzw. RTCIceTransport-statechange besser geeignet als das Abfragen in festen Abständen.
"disconnected" ist oft nur vorübergehend, etwa bei einem Netzwechsel. Einen ICE-Neustart löst man in der Regel erst bei "failed" aus.
Mit Bundling (bundlePolicy: "max-bundle") gibt es normalerweise nur einen Transport-Eintrag. Ohne Bundling können mehrere Einträge vorkommen, die jeweils einen eigenen iceState haben.
Der Wert "completed" tritt in Browsern nur selten auf.

Siehe auch

RTCTransportStats RTCTransportStats.dtlsState RTCTransportStats.selectedCandidatePairId RTCIceTransport.state RTCPeerConnection.getStats() RTCPeerConnection.iceConnectionState RTCPeerConnection.restartIce()