RTCIceCandidatePairStats.nominated — Eigenschaft · JavaScript-Referenz

Signatur

RTCIceCandidatePairStats.nominated

Beschreibung

Die Eigenschaft nominated des Wörterbuchs RTCIceCandidatePairStats zeigt an, ob das beschriebene Paar aus lokalem und entferntem ICE-Kandidaten nominiert wurde. Im ICE-Protokoll (RFC 8445) nominiert der kontrollierende Agent (controlling agent) ein erfolgreich geprüftes Paar. Damit legt er fest, dass dieses Paar für den Datenaustausch genutzt werden soll.

Du bekommst den Wert über RTCPeerConnection.getStats(). Im zurückgegebenen RTCStatsReport haben die Einträge für Kandidatenpaare den type "candidate-pair". Typische Einsatzgebiete sind die Fehlersuche bei Verbindungsproblemen, Monitoring-Dashboards und die Frage, welche Route eine Verbindung tatsächlich nimmt: direkt (host), über NAT (srflx) oder über einen TURN-Relay (relay).

Beachte: nominated === true heißt nicht automatisch, dass gerade genau dieses Paar Daten überträgt. Das aktive Paar findest du zuverlässiger über RTCTransportStats.selectedCandidatePairId. Zusätzlich sollte das Paar im Zustand state === "succeeded" sein.

Rückgabewert

Typ

boolean | undefined

Beschreibung

true, wenn das Paar nominiert wurde, sonst false. In älteren Implementierungen kann die Eigenschaft fehlen (undefined).

Beispiele

Nominierte Kandidatenpaare auflisten

const listNominatedPairs = async (pc) => {
  const report = await pc.getStats();
  report.forEach((stats) => {
    if (stats.type === 'candidate-pair' && stats.nominated) {
      console.log(`Paar ${stats.id}: Zustand=${stats.state}, RTT=${stats.currentRoundTripTime ?? '–'} s`);
    }
  });
};

// Nutzung, sobald die Verbindung steht
// pc.addEventListener('connectionstatechange', () => {
//   if (pc.connectionState === 'connected') listNominatedPairs(pc);
// });

Paar CPabc123_def456: Zustand=succeeded, RTT=0.023 s

Aktives Paar über den Transport bestimmen und Kandidatentypen ausgeben

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

  // Bevorzugt: selectedCandidatePairId aus den Transport-Statistiken
  report.forEach((s) => {
    if (s.type === 'transport' && s.selectedCandidatePairId) {
      pair = report.get(s.selectedCandidatePairId);
    }
  });

  // Rückfall: nominiertes und erfolgreiches Paar
  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);
  const remote = report.get(pair.remoteCandidateId);
  return {
    nominated: pair.nominated,
    local: `${local.candidateType} ${local.address ?? ''}:${local.port}`,
    remote: `${remote.candidateType} ${remote.address ?? ''}:${remote.port}`
  };
};

getActiveRoute(pc).then((route) => console.log(route));

{ nominated: true, local: 'host 192.168.1.20:54321', remote: 'relay 203.0.113.5:3478' }

Nominierung überwachen und TURN-Nutzung erkennen

const watchNomination = (pc, intervalMs = 2000) => {
  const timer = setInterval(async () => {
    if (pc.connectionState === 'closed') return clearInterval(timer);
    const report = await pc.getStats();
    for (const s of report.values()) {
      if (s.type !== 'candidate-pair' || !s.nominated) continue;
      const local = report.get(s.localCandidateId);
      if (local?.candidateType === 'relay') {
        console.warn('Verbindung läuft über TURN-Relay – höhere Latenz möglich.');
      }
    }
  }, intervalMs);
  return () => clearInterval(timer);
};

const stop = watchNomination(pc);
// später: stop();

Verbindung läuft über TURN-Relay – höhere Latenz möglich.

// Wichtig · Fallstricke

Nominiert heißt nicht aktiv: Es können mehrere Paare nominiert sein, zum Beispiel nach einem ICE-Neustart. Das tatsächlich genutzte Paar findest du über RTCTransportStats.selectedCandidatePairId.
Die Rolle spielt eine Rolle: Nur der kontrollierende Agent nominiert. Beim kontrollierten Agenten wird nominated erst true, wenn die Nominierung per STUN-Flag USE-CANDIDATE angekommen ist.
Die veraltete Eigenschaft selected (nur Firefox) solltest du nicht mehr verwenden. Nimm stattdessen selectedCandidatePairId.
Browser-Kompatibilität: Aktuelle Chromium-Browser, Firefox und Safari unterstützen die Eigenschaft. Ältere Versionen liefern sie eventuell nicht, prüfe also defensiv (stats.nominated === true).
Leistung: getStats() ist asynchron und kostet Rechenzeit. Frag die Werte nicht häufiger als etwa einmal pro Sekunde ab.
Datenschutz: Statistiken zu Kandidaten können lokale IP-Adressen enthalten. Speichere sie in Telemetriedaten nur anonymisiert.

Siehe auch

RTCIceCandidatePairStats.priority RTCIceCandidatePairStats.selected RTCIceCandidatePairStats.state RTCIceCandidatePairStats.id RTCIceCandidatePairStats.writable