RTCIceCandidateStats.priority — Eigenschaft · JavaScript-Referenz

Signatur

RTCIceCandidateStats.priority

Beschreibung

Die Eigenschaft priority gehört zu einem RTCIceCandidateStats-Objekt. Solche Objekte liefert RTCPeerConnection.getStats() für Einträge vom Typ "local-candidate" und "remote-candidate". Der Wert zeigt, wie stark der ICE-Agent einen Kandidaten bevorzugt: Je höher die Zahl, desto eher bildet der Kandidat ein Kandidatenpaar, das tatsächlich genutzt wird.

Die Priorität wird nach RFC 8445, Abschnitt 5.1.2 berechnet: priority = 2^24 × Typpräferenz + 2^8 × lokale Präferenz + (256 − Komponenten-ID). Die empfohlenen Typpräferenzen sind 126 für host, 110 für prflx, 100 für srflx und 0 für relay. Der Wert liegt zwischen 1 und 2³¹ − 1.

In der Praxis brauchen Sie priority vor allem zur Fehlersuche bei Verbindungsproblemen. Sie sehen damit, warum ein bestimmter Kandidat (z. B. ein TURN-Relay statt einer direkten Host-Verbindung) ausgewählt wurde. Außerdem können Sie aus dem Wert Typpräferenz, lokale Präferenz und Komponente zurückrechnen.

Rückgabewert

Typ

number

Beschreibung

Eine positive 32-Bit-Ganzzahl (1 bis 2³¹ − 1) mit der Priorität des Kandidaten. Ist sie nicht verfügbar, kann undefined zurückkommen.

Beispiele

Prioritäten aller lokalen Kandidaten ausgeben

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

// Kurz warten, bis ICE Kandidaten gesammelt hat
await new Promise((r) => setTimeout(r, 1000));

const stats = await pc.getStats();
stats.forEach((report) => {
  if (report.type === 'local-candidate') {
    console.log(report.candidateType, report.protocol, report.priority);
  }
});

host udp 2122260223 srflx udp 1686052607

Priorität nach RFC 8445 zerlegen

const decodePriority = (priority) => ({
  typePreference: priority >>> 24,
  localPreference: (priority >>> 8) & 0xffff,
  componentId: 256 - (priority & 0xff)
});

console.log(decodePriority(2130706431));

{ typePreference: 126, localPreference: 65535, componentId: 1 }

Kandidaten des ausgewählten Paares analysieren

const logSelectedPair = async (pc) => {
  const stats = await pc.getStats();
  let pair;
  stats.forEach((r) => {
    if (r.type === 'candidate-pair' && r.nominated && r.state === 'succeeded') pair = r;
  });
  if (!pair) return console.log('Kein aktives Paar');

  const local = stats.get(pair.localCandidateId);
  const remote = stats.get(pair.remoteCandidateId);
  console.log(`Lokal:  ${local.candidateType} (Priorität ${local.priority})`);
  console.log(`Remote: ${remote.candidateType} (Priorität ${remote.priority})`);
};

// Aufruf z. B. nach Verbindungsaufbau:
// pc.addEventListener('iceconnectionstatechange', () => logSelectedPair(pc));

Lokal: host (Priorität 2122260223) Remote: host (Priorität 2122194687)

// Wichtig · Fallstricke

Nicht mit der Paar-Priorität verwechseln: priority gilt für einen einzelnen Kandidaten. Die Reihenfolge der Kandidatenpaare ergibt sich aus den Prioritäten beider Seiten nach einer eigenen Formel in RFC 8445. Ein Kandidat mit hoher Priorität landet also nicht automatisch im gewählten Paar.
Die lokale Präferenz legt jeder Browser selbst fest, z. B. nach Netzwerkschnittstelle, IPv4/IPv6 oder TCP/UDP. Absolute Werte lassen sich deshalb nicht zwischen Browsern vergleichen.
Zum Zerlegen des Werts sollten Sie >>> statt >> verwenden, damit keine Vorzeichenprobleme entstehen.
Aus Datenschutzgründen (mDNS, Richtlinien zur IP-Preisgabe) werden manche Kandidaten verschleiert oder gar nicht gemeldet. Die sichtbare Liste kann deshalb unvollständig sein.
Die Browser unterstützen die Eigenschaft unterschiedlich gut, und ältere Versionen liefern einzelne Statistikfelder teils nicht. Prüfen Sie daher vorher auf undefined.

Siehe auch

RTCIceCandidateStats RTCPeerConnection.getStats() RTCIceCandidate.priority RTCIceCandidateStats.candidateType RTCIceCandidatePairStats RTCIceCandidateStats.foundation RTCIceCandidateStats.localCandidateId