RTCIceCandidatePairStats

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

Das RTCIceCandidatePairStats-Wörterbuch der WebRTC API wird verwendet, um Statistiken bereitzustellen, die Einblick in die Qualität und Leistung einer RTCPeerConnection geben, während diese verbunden und konfiguriert ist, wie es durch das angegebene Paar von ICE-Kandidaten beschrieben wird.

Die Statistiken können erhalten werden, indem man den RTCStatsReport durchläuft, der von RTCPeerConnection.getStats() zurückgegeben wird, bis man einen Eintrag mit dem type von "candidate-pair" findet.

Instanz-Eigenschaften

availableIncomingBitrate Optional

Eine Zahl, die die verfügbare eingehende Kapazität des Netzwerks darstellt. Dies gibt die Gesamtanzahl der pro Sekunde für alle eingehenden RTP-Streams des Kandidatenpaars verfügbaren Bits an. Es wird weder die Größe des Internetprotokoll-(IP)-Overheads noch andere Transportschichten wie TCP oder UDP berücksichtigt.

availableOutgoingBitrate Optional

Eine Zahl, die die ungefähre verfügbare ausgehende Kapazität des Netzwerks darstellt. Dies gibt die Gesamtanzahl der pro Sekunde für alle ausgehenden RTP-Streams des Kandidatenpaars verfügbaren Bits an. Dies berücksichtigt weder die Größe des IP-Overheads noch andere Transportschichten wie TCP oder UDP.

bytesDiscardedOnSend Optional Experimentell

Eine Ganzzahl, die die Gesamtzahl der aufgrund von Socket-Fehlern bei diesem Kandidatenpaar verworfenen Bytes darstellt.

bytesReceived Optional

Eine Ganzzahl, die die Gesamtzahl der Nutzlast-Bytes darstellt, die bei diesem Kandidatenpaar empfangen wurden.

bytesSent Optional

Eine Ganzzahl, die die Gesamtzahl der gesendeten Nutzlast-Bytes bei diesem Kandidatenpaar darstellt (die Gesamtanzahl der gesendeten Bytes ohne Header, Puffer oder anderes Protokoll-Overhead).

consentRequestsSent Optional Experimentell

Eine Ganzzahl, die die Gesamtzahl der auf diesem Kandidatenpaar gesendeten STUN-Zustimmungsanfragen darstellt.

currentRoundTripTime Optional

Eine Zahl, die die Gesamtzeit in Sekunden darstellt, die zwischen der zuletzt gesendeten STUN-Anfrage und dem Empfang der Antwort vergangen ist. Dies kann auf Anfragen basieren, die an der Bestätigung der Berechtigung zur Eröffnung der Verbindung beteiligt waren.

lastPacketReceivedTimestamp Optional

Ein DOMHighResTimeStamp-Wert, der die Zeit angibt, zu der das letzte Paket vom entfernten Peer für dieses Kandidatenpaar empfangen wurde. Zeitstempel werden für STUN-Pakete nicht aufgezeichnet.

lastPacketSentTimestamp Optional

Ein DOMHighResTimeStamp-Wert, der die Zeit angibt, zu der das letzte Paket vom lokalen Peer zum entfernten Peer für dieses Kandidatenpaar gesendet wurde. Zeitstempel werden für STUN-Pakete nicht aufgezeichnet.

localCandidateId Optional

Ein String, der die eindeutige ID des RTCIceCandidate aus den Daten im RTCIceCandidateStats-Objekt darstellt, das Statistiken über den lokalen Kandidaten des Kandidatenpaars bereitstellt.

nominated Optional

Ein Boolean-Wert, der, wenn true, anzeigt, dass das durch dieses Objekt beschriebene Kandidatenpaar für die Verwendung vorgeschlagen wurde und verwendet wird (oder wurde), wenn seine Priorität die höchste unter den nominierten Kandidatenpaaren ist. Einzelheiten finden Sie in RFC 5245, Abschnitt 7.1.3.2.4.

packetsDiscardedOnSend Optional Experimentell

Eine Ganzzahl, die die Gesamtzahl der aufgrund von Socket-Fehlern bei diesem Kandidatenpaar verworfenen Pakete darstellt.

packetsReceived Optional Experimentell

Eine Ganzzahl, die die Gesamtzahl der bei diesem Kandidatenpaar empfangenen Pakete darstellt.

packetsSent Optional Experimentell

Eine Ganzzahl, die die Gesamtzahl der bei diesem Kandidatenpaar gesendeten Pakete darstellt.

remoteCandidateId Optional

Ein String, der eine eindeutige ID enthält, die dem entfernten Kandidaten entspricht, aus dem die Daten zum Erstellen des RTCIceCandidateStats-Objekts stammen, das das entfernte Ende der Verbindung beschreibt.

requestsReceived Optional

Eine Ganzzahl, die die Gesamtzahl der erhaltenen Konnektivitätsüberprüfungsanfragen darstellt, einschließlich erneuter Übermittlungen. Dieser Wert umfasst sowohl Konnektivitätsüberprüfungen als auch STUN-Zustimmungsüberprüfungen.

requestsSent Optional

Eine Ganzzahl, die die Gesamtzahl der gesendeten Konnektivitätsüberprüfungsanfragen darstellt, ohne erneute Übermittlungen.

responsesReceived Optional

Eine Ganzzahl, die die Gesamtzahl der erhaltenen Konnektivitätsüberprüfungsantworten darstellt.

responsesSent Optional

Eine Ganzzahl, die die Gesamtzahl der gesendeten Konnektivitätsüberprüfungsantworten darstellt. Dies umfasst sowohl Konnektivitätsüberprüfungsanfragen als auch STUN-Zustimmungsanfragen.

state Optional

Ein String, der den Status der Verbindung zwischen den beiden Kandidaten angibt.

totalRoundTripTime Optional

Eine Zahl, die die gesamte verstrichene Zeit in Sekunden angibt, die zwischen dem Senden von STUN-Anfragen und dem Erhalt von Antworten darauf vergangen ist, für alle bisher bei diesem Kandidatenpaar gemachten Anfragen. Dies umfasst sowohl Konnektivitätsüberprüfungen als auch Zustimmungsüberprüfungsanfragen. Sie können die durchschnittliche Round Trip Time (RTT) berechnen, indem Sie diesen Wert durch responsesReceived teilen.

transportId Optional

Ein String, der das RTCIceTransport, das zur Ermittlung der transportbezogenen Statistiken (wie in RTCTransportStats gefunden) inspiziert wurde, eindeutig identifiziert und zur Erstellung dieses Objekts verwendet wurde.

Allgemeine Instanz-Eigenschaften

Die folgenden Eigenschaften sind allen WebRTC-Statistikobjekten gemeinsam.

id

Ein String, der das Objekt, das zur Erzeugung dieses Statistikensatzes überwacht wird, eindeutig identifiziert.

timestamp

Ein DOMHighResTimeStamp-Objekt, das die Zeit angibt, zu der die Probe für dieses Statistikobjekt entnommen wurde.

type

Ein String mit dem Wert "candidate-pair", der den Typ der Statistiken angibt, die das Objekt enthält.

Veraltete Eigenschaften

Die folgenden Eigenschaften wurden aus der Spezifikation entfernt und sollten nicht mehr verwendet werden. Sie sollten jeden vorhandenen Code so schnell wie möglich aktualisieren, um deren Verwendung zu vermeiden. Überprüfen Sie die Kompatibilitätstabelle für Details darüber, welche Browser sie unterstützen und in welchen Versionen.

priority Veraltet Optional Nicht standardisiert

Ein Ganzzahwert, der die Priorität des Kandidatenpaars angibt.

readable Veraltet Optional Nicht standardisiert

Ein Boolean-Wert, der angibt, ob Daten über die durch das Kandidatenpaar beschriebene Verbindung gesendet werden können oder nicht.

writable Veraltet Optional Nicht standardisiert

Ein Boolean-Wert, der angibt, ob Daten über die durch das Kandidatenpaar beschriebene Verbindung empfangen werden können oder nicht.

Nicht-standardmäßige Eigenschaften

selected Nicht standardisiert Optional

Ein Firefox-spezifischer Boolean-Wert, der true ist, wenn das durch dieses Objekt beschriebene Kandidatenpaar dasjenige ist, das derzeit verwendet wird. Der spezifikationskonforme Weg, das ausgewählte Kandidatenpaar zu bestimmen, besteht darin, nach einem Statistikobjekt des Typs transport zu suchen, welches ein RTCTransportStats-Objekt ist. Die selectedCandidatePairId-Eigenschaft dieses Objekts gibt an, ob der angegebene Transport derjenige ist, der verwendet wird.

Nutzungsnotizen

Das derzeit aktive ICE-Kandidatenpaar — falls vorhanden — kann ermittelt werden, indem man die RTCIceTransport-Methode getSelectedCandidatePair() aufruft, die ein RTCIceCandidatePair-Objekt oder null zurückgibt, wenn kein Paar ausgewählt ist. Das aktive Kandidatenpaar beschreibt die aktuelle Konfiguration der beiden Enden der RTCPeerConnection.

Jedes Kandidatenpaar, das nicht das aktive Paar von Kandidaten für einen Transport ist, wird gelöscht, wenn das RTCIceTransport einen ICE-Neustart durchführt, zu diesem Zeitpunkt kehrt der state des ICE-Transports zu new zurück und die Verhandlung beginnt erneut. Weitere Informationen finden Sie unter ICE-Neustart.

Beispiel

Dieses Beispiel berechnet die durchschnittliche Zeit, die zwischen Konnektivitätsüberprüfungen verstrichen ist.

js
if (rtcStats && rtcStats.type === "candidate-pair") {
  let elapsed =
    (rtcStats.lastRequestTimestamp - rtcStats.firstRequestTimestamp) /
    rtcStats.requestsSent;

  console.log(`Average time between ICE connectivity checks: ${elapsed} ms.`);
}

Der Code beginnt damit, rtcStats zu überprüfen, um festzustellen, ob dessen type candidate-pair ist. Wenn dies der Fall ist, wissen wir, dass rtcStats tatsächlich ein RTCIceCandidatePairStats-Objekt ist. Dann können wir die durchschnittliche Zeit berechnen, die zwischen den STUN-Konnektivitätsüberprüfungen vergangen ist, und diese Informationen protokollieren.

Spezifikationen

Specification
Identifiers for WebRTC's Statistics API
# dom-rtcstatstype-candidate-pair

Browser-Kompatibilität

BCD tables only load in the browser