RTCIceParameters.usernameFragment — Eigenschaft · JavaScript-Referenz

Signatur

RTCIceParameters.usernameFragment

Beschreibung

Die Eigenschaft usernameFragment des Wörterbuchs RTCIceParameters ist ein String. Er enthält das Username-Fragment (kurz „ufrag“) einer ICE-Sitzung (Interactive Connectivity Establishment). Zusammen mit dem password bilden ufrag und Passwort die Zugangsdaten, mit denen die Peers ihre STUN-Konnektivitätsprüfungen gegenseitig authentifizieren. Beim Verbindungstest wird der STUN-Benutzername aus beiden Fragmenten zusammengesetzt: remoteUfrag:localUfrag.

Ein RTCIceParameters-Objekt bekommst du nicht direkt, sondern über RTCIceTransport.getLocalParameters() oder RTCIceTransport.getRemoteParameters(). Den RTCIceTransport erreichst du wiederum über RTCRtpSender.transport.iceTransport bzw. RTCSctpTransport.transport.iceTransport. Derselbe Wert steht in der SDP als Attribut a=ice-ufrag:… und in jedem RTCIceCandidate als usernameFragment.

Nützlich ist die Eigenschaft vor allem für Diagnose und Debugging: Du kannst damit Kandidaten der richtigen ICE-Generation zuordnen, einen ICE-Neustart erkennen (der ufrag ändert sich dabei) oder Signalisierungsdaten mit dem tatsächlichen Transportzustand abgleichen. Der Wert gilt nur so lange, wie die aktuelle ICE-Sitzung läuft.

Rückgabewert

Typ

string

Beschreibung

Das Username-Fragment der ICE-Sitzung, laut RFC 8839 4 bis 256 Zeichen aus ALPHA, DIGIT, + und /. Ist noch kein Wert ausgehandelt, kann das Feld fehlen oder ein leerer String sein.

Beispiele

Lokales und entferntes ufrag auslesen

const pc = new RTCPeerConnection();
pc.addTransceiver('audio');

pc.addEventListener('connectionstatechange', () => {
  if (pc.connectionState !== 'connected') return;

  const [sender] = pc.getSenders();
  const ice = sender.transport?.iceTransport;
  if (!ice || typeof ice.getLocalParameters !== 'function') {
    console.warn('RTCIceTransport-Parameter werden nicht unterstützt');
    return;
  }

  const local = ice.getLocalParameters();
  const remote = ice.getRemoteParameters();
  console.log('Lokales ufrag:', local?.usernameFragment);
  console.log('Entferntes ufrag:', remote?.usernameFragment);
});

Lokales ufrag: fX9k Entferntes ufrag: 3aQz

ufrag mit der lokalen SDP abgleichen

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

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

// ufrag aus der SDP extrahieren
const sdpUfrag = pc.localDescription.sdp.match(/^a=ice-ufrag:(.+)$/m)?.[1]?.trim();
console.log('ufrag laut SDP:', sdpUfrag);

// Später, sobald der Transport existiert:
const ice = pc.sctp?.transport?.iceTransport;
const params = ice?.getLocalParameters?.();
if (params) {
  console.log('Übereinstimmung:', params.usernameFragment === sdpUfrag);
}

ufrag laut SDP: Lk2p Übereinstimmung: true

ICE-Neustart anhand des ufrag erkennen

const watchIceRestart = (pc) => {
  let lastUfrag = null;

  pc.addEventListener('iceconnectionstatechange', () => {
    const ice = pc.getSenders()[0]?.transport?.iceTransport;
    const ufrag = ice?.getLocalParameters?.()?.usernameFragment;
    if (!ufrag) return;

    if (lastUfrag && ufrag !== lastUfrag) {
      console.log(`ICE-Neustart: ${lastUfrag} → ${ufrag}`);
    }
    lastUfrag = ufrag;
  });
};

// Aufruf: watchIceRestart(pc); später pc.restartIce();

ICE-Neustart: fX9k → Qm7r

// Wichtig · Fallstricke

Browserunterstützung: RTCIceTransport.getLocalParameters() und getRemoteParameters() funktionieren in Chromium-Browsern und Safari. In Firefox fehlen sie bisher weitgehend. Prüfe vor dem Aufruf, ob die Methoden existieren, oder lies den ufrag als Ausweichlösung aus der SDP (a=ice-ufrag).
Nur Lesezugriff: Den ufrag setzt der Browser. Wenn du ihn von Hand in der SDP änderst („SDP-Munging“), ist das nicht standardkonform und kann die Aushandlung scheitern lassen.
Wert ändert sich: Nach pc.restartIce() oder einem Angebot mit iceRestart: true gibt es neue ufrag- und Passwortwerte. Speichere den Wert also nicht dauerhaft zwischen.
Kandidaten zuordnen: Kommt ein entfernter Kandidat mit einem veralteten usernameFragment an, gehört er zu einer früheren ICE-Generation und kann verworfen werden.
Sicherheit: Der ufrag allein ist kein Geheimnis, denn er steht offen in der SDP. Das zugehörige password solltest du dagegen nicht protokollieren oder an Dritte weitergeben.
Wenn noch keine entfernte Beschreibung gesetzt ist, liefert getRemoteParameters() null.

Siehe auch

RTCIceParameters RTCIceParameters.password RTCIceTransport.getLocalParameters() RTCIceTransport.getRemoteParameters() RTCIceCandidate.usernameFragment RTCPeerConnection.restartIce() PublicKeyCredential.authenticatorAttachment