RTCPeerConnectionIceErrorEvent.url — Eigenschaft · JavaScript-Referenz

Signatur

RTCPeerConnectionIceErrorEvent.url

Beschreibung

Die Eigenschaft url des RTCPeerConnectionIceErrorEvent ist schreibgeschützt. Sie enthält die URL des STUN- oder TURN-Servers, bei dem die ICE-Kandidatensuche (ICE Candidate Gathering) fehlgeschlagen ist, z. B. "stun:stun.example.org:3478" oder "turn:turn.example.org:3478?transport=udp". Das Ereignis wird als icecandidateerror an einer RTCPeerConnection ausgelöst.

Wenn du in iceServers mehrere Server einträgst, kannst du über url herausfinden, welcher Server das Problem hat. Das ist bei der Fehlersuche in WebRTC-Anwendungen sehr nützlich, etwa bei falschen TURN-Zugangsdaten (Fehlercode 401), einem nicht erreichbaren Server (Codes im Bereich 700–799) oder Firewall-Problemen.

Die URL entspricht dem Eintrag aus der RTCConfiguration. Häufig wertet man sie zusammen mit errorCode, errorText, address und port aus. Damit lassen sich aussagekräftige Log-Einträge oder Telemetriedaten erzeugen.

Rückgabewert

Typ

string

Beschreibung

Die STUN- oder TURN-URL (Schema stun:, stuns:, turn: oder turns:) des Servers, bei dem der Fehler aufgetreten ist.

Beispiele

Fehlerhaften ICE-Server mit addEventListener protokollieren

const pc = new RTCPeerConnection({
  iceServers: [
    { urls: 'stun:stun.l.google.com:19302' },
    { urls: 'turn:turn.example.org:3478', username: 'user', credential: 'falsch' }
  ]
});

pc.addEventListener('icecandidateerror', (event) => {
  console.warn(`ICE-Fehler bei ${event.url}: ${event.errorCode} ${event.errorText}`);
});

// Kandidatensuche anstoßen
pc.createDataChannel('test');
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

ICE-Fehler bei turn:turn.example.org:3478: 401 Unauthorized

Fehler pro Server zählen (on-Property)

const fehlerProServer = new Map();
const pc = new RTCPeerConnection({
  iceServers: [{ urls: ['stun:stun1.example.org', 'stun:stun2.example.org'] }]
});

pc.onicecandidateerror = ({ url, errorCode }) => {
  fehlerProServer.set(url, (fehlerProServer.get(url) ?? 0) + 1);
  if (errorCode >= 700 && errorCode <= 799) {
    console.log(`Server nicht erreichbar: ${url}`);
  }
};

pc.onicegatheringstatechange = () => {
  if (pc.iceGatheringState === 'complete') {
    console.log(Object.fromEntries(fehlerProServer));
  }
};

pc.createDataChannel('x');
await pc.setLocalDescription(await pc.createOffer());

Server nicht erreichbar: stun:stun2.example.org { "stun:stun2.example.org": 1 }

TURN-Fehler ohne Zugangsdaten an Telemetrie senden

const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'turns:turn.example.org:443?transport=tcp', username: 'u', credential: 'p' }]
});

pc.addEventListener('icecandidateerror', (event) => {
  const { url, errorCode, errorText, port } = event;
  // Nur Server-URL senden, keine Zugangsdaten
  navigator.sendBeacon('/telemetrie/ice', JSON.stringify({ url, errorCode, errorText, port }));
});

// Wichtig · Fallstricke

Nicht jeder Fehler ist ein Problem: Das Ereignis icecandidateerror tritt oft auf, wenn ein einzelner Server oder eine einzelne Netzwerkschnittstelle nicht funktioniert. Die Verbindung kann trotzdem über andere Kandidaten zustande kommen. Prüfe deshalb zusätzlich iceConnectionState bzw. connectionState.
Die Eigenschaft ist schreibgeschützt. Das URL-Format richtet sich nach RFC 7064/7065 (stun:, turn: usw.) und ist keine HTTP-URL.
Die URL enthält keine Zugangsdaten. Trotzdem legt sie deine Infrastruktur offen. Überlege, ob du sie ungefiltert in öffentliche Logs schreiben willst.
Kompatibilität: Chromium hat das Ereignis früh unterstützt, Firefox erst ab Version 118 und Safari ab 16.4. Ältere Chromium-Versionen boten statt address die veraltete Eigenschaft hostCandidate an. Wenn der Wert wichtig ist, prüfe vorher mit 'url' in event, ob er vorhanden ist.

Siehe auch

RTCPeerConnectionIceErrorEvent RTCPeerConnectionIceErrorEvent.errorCode RTCPeerConnectionIceErrorEvent.errorText RTCPeerConnectionIceErrorEvent.address RTCPeerConnection RTCPeerConnectionIceEvent.url