RTCIceCandidateStats.url — Eigenschaft · JavaScript-Referenz

Signatur

RTCIceCandidateStats.url

Beschreibung

Die Eigenschaft url ist ein Feld der Statistik-Objekte vom Typ RTCIceCandidateStats. Diese Objekte liefert RTCPeerConnection.getStats() mit dem type "local-candidate" oder "remote-candidate". Der Wert ist ein String mit der ICE-Server-URL aus der Konfiguration der Verbindung, zum Beispiel "stun:stun.example.org:3478" oder "turn:turn.example.org:3478?transport=udp".

Das Feld gibt es nur bei lokalen Kandidaten mit dem candidateType "srflx" (server-reflexiv, über STUN ermittelt) oder "relay" (über einen TURN-Server weitergeleitet). Bei Host-Kandidaten ("host"), bei peer-reflexiven Kandidaten ("prflx") und bei allen entfernten Kandidaten fehlt es. Dann ist der Wert undefined.

In der Praxis nutzt man url vor allem für Fehlersuche und Überwachung: Man sieht damit, welcher von mehreren konfigurierten STUN- oder TURN-Servern tatsächlich Kandidaten liefert und über welchen Server ein weitergeleiteter Kandidat des aktiven Kandidatenpaars läuft. So lässt sich die Auslastung der TURN-Server messen, oder man erkennt falsch konfigurierte Server.

Rückgabewert

Typ

string | undefined

Beschreibung

Die URL des ICE-Servers (Schema stun:, stuns:, turn: oder turns:), über den der Kandidat ermittelt wurde. Bei Host-Kandidaten, peer-reflexiven Kandidaten und entfernten Kandidaten ist der Wert undefined.

Beispiele

ICE-Server aller lokalen Kandidaten auflisten

const pc = new RTCPeerConnection({
  iceServers: [
    { urls: 'stun:stun.l.google.com:19302' },
    { urls: 'turn:turn.example.org:3478', username: 'user', credential: 'geheim' }
  ]
});
pc.createDataChannel('test');
await pc.setLocalDescription(await pc.createOffer());

// Etwas warten, damit Kandidaten gesammelt werden
await new Promise((r) => setTimeout(r, 2000));

const stats = await pc.getStats();
stats.forEach((report) => {
  if (report.type === 'local-candidate') {
    console.log(report.candidateType, report.address, report.url ?? '(kein Server)');
  }
});

host 192.168.1.20 (kein Server) srflx 203.0.113.7 stun:stun.l.google.com:19302 relay 198.51.100.4 turn:turn.example.org:3478

TURN-Server des aktiven Kandidatenpaars ermitteln

const getActiveIceServer = async (pc) => {
  const stats = await pc.getStats();
  let pair;
  stats.forEach((r) => {
    if (r.type === 'transport' && r.selectedCandidatePairId) {
      pair = stats.get(r.selectedCandidatePairId);
    }
  });
  if (!pair) return null;

  const local = stats.get(pair.localCandidateId);
  return {
    typ: local.candidateType,
    server: local.url ?? null
  };
};

console.log(await getActiveIceServer(pc));

{ typ: 'relay', server: 'turn:turn.example.org:3478' }

Kandidaten pro ICE-Server zählen (Monitoring)

const countCandidatesPerServer = async (pc) => {
  const counts = {};
  const stats = await pc.getStats();
  for (const report of stats.values()) {
    if (report.type === 'local-candidate' && report.url) {
      counts[report.url] = (counts[report.url] ?? 0) + 1;
    }
  }
  return counts;
};

console.table(await countCandidatesPerServer(pc));

{ 'stun:stun.l.google.com:19302': 2, 'turn:turn.example.org:3478': 1 }

// Wichtig · Fallstricke

Nicht immer vorhanden: Bei host- und prflx-Kandidaten sowie bei allen remote-candidate-Berichten fehlt url. Den Wert deshalb immer auf undefined prüfen, etwa mit ?? oder optionaler Verkettung.
Browser-Unterstützung: Chromium-Browser und Safari liefern das Feld. In Firefox fehlte es lange oder war unvollständig. Den Wert also nicht als garantiert voraussetzen.
Zeitpunkt: Kandidaten entstehen erst nach setLocalDescription() während der ICE-Sammlung. Ein zu früher Aufruf von getStats() liefert noch keine srflx- oder relay-Kandidaten.
Datenschutz: Die Statistiken enthalten Server-URLs und IP-Adressen. Beim Senden an ein Analyse-Backend sensible Daten nicht ungefiltert weitergeben. Zugangsdaten für TURN-Server stehen nicht in url.
Wird ein Server in der Konfiguration mit mehreren urls angegeben, enthält url genau die eine URL, über die der Kandidat tatsächlich ermittelt wurde.

Siehe auch

RTCIceCandidateStats RTCIceCandidateStats.candidateType RTCIceCandidateStats.address RTCPeerConnection.prototype.getStats() RTCIceCandidatePairStats RTCPeerConnection RTCIceCandidateStats.id