RTCIceCandidateStats.protocol — Eigenschaft · JavaScript-Referenz

Signatur

RTCIceCandidateStats.protocol

Beschreibung

Die Eigenschaft protocol gehört zum Wörterbuch RTCIceCandidateStats. Dieses Wörterbuch beschreibt Statistikeinträge vom Typ "local-candidate" und "remote-candidate", die RTCPeerConnection.getStats() in einem RTCStatsReport zurückgibt. Der Wert zeigt, welches Transportprotokoll der jeweilige ICE-Kandidat nutzt: "udp" oder "tcp".

Das ist vor allem bei der Fehlersuche und Überwachung der Verbindungsqualität hilfreich. WebRTC bevorzugt UDP, weil es eine geringere Latenz hat und verlorene Pakete nicht erneut sendet und so keine Staus verursacht. Blockieren Firewalls oder Unternehmensnetzwerke UDP, weicht der Browser auf TCP-Kandidaten oder einen TURN-Server über TCP/TLS aus. Wenn du protocol für das aktive Kandidatenpaar ausliest, erkennst du, ob eine Verbindung auf das langsamere TCP ausgewichen ist. Das erklärt oft höhere Verzögerungen oder Ruckler.

Bei Relay-Kandidaten (candidateType === "relay") beschreibt protocol das Protokoll zwischen TURN-Server und entferntem Peer. Wie der Client selbst mit dem TURN-Server verbunden ist, steht in der separaten Eigenschaft relayProtocol ("udp", "tcp" oder "tls").

Rückgabewert

Typ

string ("udp" | "tcp")

Beschreibung

Ein String mit dem Transportprotokoll des Kandidaten, entweder "udp" oder "tcp". Er entspricht dem Feld protocol der zugehörigen RTCIceCandidate.

Beispiele

Protokolle aller lokalen und entfernten Kandidaten auflisten

// pc ist eine bereits verbundene RTCPeerConnection
const listCandidateProtocols = async (pc) => {
  const report = await pc.getStats();
  report.forEach((stats) => {
    if (stats.type === 'local-candidate' || stats.type === 'remote-candidate') {
      console.log(
        `${stats.type}: ${stats.address ?? '(verborgen)'}:${stats.port} ` +
        `– ${stats.protocol} (${stats.candidateType})`
      );
    }
  });
};

await listCandidateProtocols(pc);

local-candidate: 192.168.1.20:54321 – udp (host) local-candidate: 203.0.113.5:61000 – udp (srflx) remote-candidate: 198.51.100.7:49152 – udp (host)

Prüfen, ob die aktive Verbindung auf TCP ausgewichen ist

const getActiveProtocol = async (pc) => {
  const report = await pc.getStats();
  let pair;

  // Das ausgewählte Kandidatenpaar über den Transport finden
  report.forEach((s) => {
    if (s.type === 'transport' && s.selectedCandidatePairId) {
      pair = report.get(s.selectedCandidatePairId);
    }
  });
  // Fallback für Browser ohne selectedCandidatePairId (z. B. Firefox)
  if (!pair) {
    report.forEach((s) => {
      if (s.type === 'candidate-pair' && s.nominated && s.state === 'succeeded') {
        pair = s;
      }
    });
  }
  if (!pair) return null;

  const local = report.get(pair.localCandidateId);
  return {
    protocol: local.protocol,
    candidateType: local.candidateType,
    relayProtocol: local.relayProtocol ?? null
  };
};

const info = await getActiveProtocol(pc);
if (info?.protocol === 'tcp' || info?.relayProtocol === 'tcp' || info?.relayProtocol === 'tls') {
  console.warn('Verbindung läuft über TCP – mit höherer Latenz rechnen.', info);
} else {
  console.log('Aktive Verbindung:', info);
}

Aktive Verbindung: { protocol: 'udp', candidateType: 'srflx', relayProtocol: null }

Protokollverteilung für ein Monitoring-Dashboard zählen

const countProtocols = async (pc) => {
  const report = await pc.getStats();
  const counts = { udp: 0, tcp: 0 };
  for (const stats of report.values()) {
    if (stats.type === 'local-candidate' && stats.protocol in counts) {
      counts[stats.protocol]++;
    }
  }
  return counts;
};

console.log(await countProtocols(pc));

{ udp: 3, tcp: 1 }

// Wichtig · Fallstricke

Protokoll und Relay-Protokoll unterscheiden: Auch bei einer TURN-Verbindung über TCP oder TLS kann protocol den Wert "udp" haben. Maßgeblich für den Weg vom Client zum TURN-Server ist relayProtocol.
Der Wert beschreibt nur einen Kandidaten. Welches Protokoll tatsächlich genutzt wird, ergibt sich erst aus dem ausgewählten candidate-pair. Dieses erreichst du über RTCTransportStats.selectedCandidatePairId, oder du suchst ein Paar mit nominated und dem Zustand "succeeded".
Die Statistik ist ein Momentaufnahme-Objekt und aktualisiert sich nicht selbst. Um Änderungen zu erkennen, etwa nach einem ICE-Neustart, musst du getStats() erneut aufrufen.
Datenschutz: Wegen mDNS-Verschleierung kann address fehlen oder eine .local-Adresse enthalten. protocol ist davon nicht betroffen.
Kompatibilität: Die Eigenschaft wird in Chromium, Firefox und Safari unterstützt. Ältere Browser liefern teilweise andere Statistik-Typen, zum Beispiel "localcandidate" ohne Bindestrich in alten Firefox-Versionen. Bei der Auswertung solltest du deshalb auf fehlende Felder vorbereitet sein.

Siehe auch

RTCIceCandidateStats RTCIceCandidateStats.relayProtocol RTCIceCandidateStats.candidateType RTCIceCandidate.protocol RTCPeerConnection.getStats() RTCIceCandidatePairStats RTCIceCandidateStats.priority