RTCTransportStats.iceLocalUsernameFragment — Eigenschaft · JavaScript-Referenz

Signatur

RTCTransportStats.iceLocalUsernameFragment

Beschreibung

Die Eigenschaft iceLocalUsernameFragment des Wörterbuchs RTCTransportStats enthält das lokale Benutzernamen-Fragment (kurz „ufrag“, im SDP als a=ice-ufrag angegeben). Die ICE-Sitzung des Transports verwendet es für Konnektivitätsprüfungen: Der STUN-Benutzername einer Anfrage setzt sich aus dem ufrag der Gegenseite und dem lokalen ufrag zusammen, getrennt durch einen Doppelpunkt.

Den Wert liest du aus dem Bericht vom Typ "transport", den RTCPeerConnection.getStats() liefert. Er hilft vor allem bei der Fehlersuche: Du kannst den Statistik-Bericht damit dem lokalen SDP zuordnen und einen ICE-Neustart (restartIce()) erkennen, denn dabei wird ein neuer ufrag erzeugt.

Die Eigenschaft ist schreibgeschützt. Solange noch keine lokale Beschreibung gesetzt ist, kann sie fehlen (undefined).

Rückgabewert

Typ

string | undefined

Beschreibung

Das aktuelle lokale ICE-Benutzernamen-Fragment, zum Beispiel "a1B2", oder undefined, wenn der Browser den Wert nicht liefert oder noch keine lokale Beschreibung gesetzt ist.

Beispiele

ufrag aus den Transport-Statistiken auslesen

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

const stats = await pc.getStats();
stats.forEach((report) => {
  if (report.type === 'transport') {
    console.log('Lokales ufrag:', report.iceLocalUsernameFragment);
  }
});

Lokales ufrag: kP3x

Mit dem ice-ufrag im lokalen SDP abgleichen

const getLocalUfragFromSdp = (sdp) =>
  sdp.match(/^a=ice-ufrag:(.+)$/m)?.[1]?.trim();

const checkUfrag = async (pc) => {
  const stats = await pc.getStats();
  const transport = [...stats.values()].find((r) => r.type === 'transport');
  const fromSdp = getLocalUfragFromSdp(pc.localDescription?.sdp ?? '');
  console.log('Stats:', transport?.iceLocalUsernameFragment, '| SDP:', fromSdp);
  return transport?.iceLocalUsernameFragment === fromSdp;
};

// Aufruf, nachdem setLocalDescription() ausgeführt wurde:
// console.log(await checkUfrag(pc));

Stats: kP3x | SDP: kP3x true

ICE-Neustart über geänderten ufrag erkennen

let lastUfrag;

const watchIceRestart = (pc, intervalMs = 2000) =>
  setInterval(async () => {
    const stats = await pc.getStats();
    for (const report of stats.values()) {
      if (report.type !== 'transport') continue;
      const ufrag = report.iceLocalUsernameFragment;
      if (lastUfrag && ufrag && ufrag !== lastUfrag) {
        console.log(`ICE-Neustart erkannt: ${lastUfrag} → ${ufrag}`);
      }
      lastUfrag = ufrag ?? lastUfrag;
    }
  }, intervalMs);

// const timer = watchIceRestart(pc);
// pc.restartIce(); // führt nach Neuverhandlung zu neuem ufrag

ICE-Neustart erkannt: kP3x → Z9qt

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Chromium-basierte Browser liefern den Wert, etwa Chrome und Edge ab Version 118. Firefox und Safari geben ihn derzeit nicht aus. Prüfe ihn daher immer auf undefined.
Der Wert ändert sich bei jedem ICE-Neustart. Speicherst du ihn zwischen, kann er veraltet sein.
Bei aktivem bundlePolicy: "max-bundle" gibt es meist nur einen Transport-Bericht. Ohne Bündelung kann es mehrere geben, jeweils mit eigenem ufrag.
Datenschutz: Der ufrag allein ist kein Geheimnis. Er steht ohnehin im SDP. Das zugehörige ICE-Passwort (ice-pwd) erscheint nicht in den Statistiken und sollte auch nicht protokolliert werden. Gib Statistik-Ausgaben trotzdem nur bedacht an Dritte weiter.

Siehe auch

RTCTransportStats RTCPeerConnection.getStats() RTCPeerConnection.restartIce() RTCTransportStats.iceState RTCTransportStats.iceRole RTCIceCandidate.usernameFragment RTCTransportStats.dtlsRole