RTCIceCandidateStats.candidateType — Eigenschaft · JavaScript-Referenz

Signatur

RTCIceCandidateStats.candidateType

Beschreibung

Die Eigenschaft candidateType gehört zu den Statistik-Objekten vom Typ "local-candidate" und "remote-candidate", die RTCPeerConnection.getStats() in einem RTCStatsReport liefert. Sie gibt an, auf welchem Weg die Adresse des ICE-Kandidaten ermittelt wurde.

Mögliche Werte (Aufzählung RTCIceCandidateType):

"host" – die tatsächliche Adresse einer lokalen Netzwerkschnittstelle (bzw. eine mDNS-Adresse wie xyz.local).
"srflx" (server reflexive) – öffentliche Adresse, die ein STUN-Server von außerhalb des NAT sieht.
"prflx" (peer reflexive) – Adresse, die erst während der Konnektivitätsprüfungen durch eine STUN-Anfrage des Gegenübers entdeckt wurde.
"relay" – Adresse eines TURN-Servers, über den der Datenverkehr weitergeleitet wird.

In der Praxis nutzt man candidateType vor allem zur Diagnose: Man ermittelt das gerade aktive Kandidatenpaar ("candidate-pair" mit nominated/state === "succeeded" bzw. über transport.selectedCandidatePairId) und prüft, ob die Verbindung direkt (host/srflx) oder über einen TURN-Relay läuft. Das ist relevant für Latenz, Serverkosten und Fehlersuche bei restriktiven Firewalls.

Rückgabewert

Typ

"host" | "srflx" | "prflx" | "relay"

Beschreibung

String aus der Aufzählung RTCIceCandidateType, der den Typ des Kandidaten beschreibt.

Beispiele

Alle lokalen und entfernten Kandidaten mit Typ auflisten

const listCandidates = async (pc) => {
  const report = await pc.getStats();
  report.forEach((stat) => {
    if (stat.type === 'local-candidate' || stat.type === 'remote-candidate') {
      console.log(`${stat.type}: ${stat.candidateType} ${stat.address ?? '?'}:${stat.port} (${stat.protocol})`);
    }
  });
};

// Aufruf nach Aufbau der Verbindung
// await listCandidates(peerConnection);

local-candidate: host 3f2a1b.local:54321 (udp) local-candidate: srflx 203.0.113.7:54321 (udp) remote-candidate: srflx 198.51.100.4:61000 (udp)

Prüfen, ob die aktive Verbindung über TURN läuft

const getActiveCandidateTypes = async (pc) => {
  const report = await pc.getStats();
  let pair;
  report.forEach((stat) => {
    if (stat.type === 'transport' && stat.selectedCandidatePairId) {
      pair = report.get(stat.selectedCandidatePairId);
    }
  });
  // Fallback, falls transport.selectedCandidatePairId fehlt (z. B. Firefox)
  if (!pair) {
    report.forEach((stat) => {
      if (stat.type === 'candidate-pair' && stat.nominated && stat.state === 'succeeded') pair = stat;
    });
  }
  if (!pair) return null;
  const local = report.get(pair.localCandidateId);
  const remote = report.get(pair.remoteCandidateId);
  return { local: local.candidateType, remote: remote.candidateType };
};

const types = await getActiveCandidateTypes(peerConnection);
if (types && (types.local === 'relay' || types.remote === 'relay')) {
  console.log('Verbindung läuft über einen TURN-Server');
} else {
  console.log('Direkte Verbindung:', types);
}

Direkte Verbindung: { local: 'srflx', remote: 'host' }

Kandidatentypen für Monitoring zählen

const countCandidateTypes = async (pc) => {
  const counts = { host: 0, srflx: 0, prflx: 0, relay: 0 };
  const report = await pc.getStats();
  for (const stat of report.values()) {
    if (stat.type === 'local-candidate' && stat.candidateType in counts) {
      counts[stat.candidateType]++;
    }
  }
  return counts;
};

console.log(await countCandidateTypes(peerConnection));

{ host: 2, srflx: 1, prflx: 0, relay: 1 }

// Wichtig · Fallstricke

Die Werte sind Abkürzungen: Es heißt "srflx", nicht "server-reflexive" – beim Vergleichen exakt diese Strings verwenden.
"relay"-Kandidaten gibt es nur, wenn in iceServers ein TURN-Server mit gültigen Zugangsdaten konfiguriert ist; "srflx" setzt einen STUN-Server voraus.
Aus Datenschutzgründen ersetzen moderne Browser lokale IP-Adressen von host-Kandidaten durch mDNS-Namen (*.local); address kann außerdem fehlen oder leer sein. candidateType bleibt davon unberührt.
Statistiken sind Momentaufnahmen – nach einem ICE-Neustart oder Netzwechsel kann sich das aktive Paar und damit der Typ ändern. getStats() daher erneut abfragen.
Die Statistik-Unterstützung unterscheidet sich zwischen Browsern (z. B. selectedCandidatePairId am Transport); einen Fallback über nominated-Kandidatenpaare vorsehen.

Siehe auch

RTCIceCandidateStats RTCPeerConnection.getStats() RTCIceCandidate.type RTCIceCandidatePairStats RTCStatsReport RTCIceCandidateStats.foundation RTCIceCandidateStats.lastPacketSentTimestamp