RTCPeerConnectionIceEvent.url — Eigenschaft · JavaScript-Referenz

Signatur

RTCPeerConnectionIceEvent.url

Beschreibung

Die schreibgeschützte Eigenschaft url eines RTCPeerConnectionIceEvent enthält die URL des STUN- oder TURN-Servers (z. B. "stun:stun.l.google.com:19302"), über den der ICE-Kandidat im Ereignis ermittelt wurde. Das Ereignis erhalten Sie im icecandidate-Handler einer RTCPeerConnection.

Die Eigenschaft hilft vor allem bei der Fehlersuche und Diagnose. Sie sehen daran, welcher der unter iceServers eingetragenen Server tatsächlich Kandidaten liefert, etwa ob ein TURN-Server erreichbar ist und Relay-Kandidaten erzeugt.

Wurde der Kandidat nicht über einen STUN- oder TURN-Server gesammelt, ist der Wert null. Das gilt zum Beispiel für host-Kandidaten, also lokale Netzwerkadressen. Auch beim abschließenden Ereignis, das mit event.candidate === null das Ende der Kandidatensuche meldet, ist der Wert null.

Die WebRTC-Spezifikation führt url nur noch aus Gründen der Abwärtskompatibilität. Für neuen Code sollten Sie event.candidate.url (RTCIceCandidate.url) verwenden. Diese Eigenschaft liefert dieselbe Information direkt am Kandidaten-Objekt.

Rückgabewert

Typ

string | null

Beschreibung

Die STUN-/TURN-URL, über die der Kandidat gesammelt wurde, oder null, wenn kein Server beteiligt war (z. B. bei host-Kandidaten oder beim Ereignis, das das Ende der Kandidatensuche meldet).

Beispiele

Herkunft jedes ICE-Kandidaten protokollieren

const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
});

pc.addEventListener('icecandidate', (event) => {
  if (!event.candidate) {
    console.log('Kandidatensuche abgeschlossen');
    return;
  }
  // Wenn möglich die moderne Eigenschaft bevorzugen, sonst auf event.url zurückgreifen
  const serverUrl = event.candidate.url ?? event.url ?? 'lokal (host)';
  console.log(`${event.candidate.type}-Kandidat von: ${serverUrl}`);
});

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

host-Kandidat von: lokal (host) srflx-Kandidat von: stun:stun.l.google.com:19302 Kandidatensuche abgeschlossen

Prüfen, ob ein TURN-Server Relay-Kandidaten liefert

const checkTurn = (turnConfig, timeoutMs = 5000) => new Promise((resolve) => {
  const pc = new RTCPeerConnection({ iceServers: [turnConfig], iceTransportPolicy: 'relay' });
  const timer = setTimeout(() => { pc.close(); resolve(false); }, timeoutMs);

  pc.onicecandidate = (event) => {
    const url = event.candidate?.url ?? event.url;
    if (event.candidate?.type === 'relay' && url?.startsWith('turn')) {
      console.log('Relay-Kandidat über', url);
      clearTimeout(timer);
      pc.close();
      resolve(true);
    }
  };

  pc.createDataChannel('probe');
  pc.createOffer().then((o) => pc.setLocalDescription(o));
});

const ok = await checkTurn({
  urls: 'turn:turn.example.com:3478',
  username: 'demo',
  credential: 'geheim'
});
console.log('TURN erreichbar:', ok);

Relay-Kandidat über turn:turn.example.com:3478 TURN erreichbar: true

Kandidaten nach Server gruppieren (Diagnose)

const pc = new RTCPeerConnection({
  iceServers: [
    { urls: 'stun:stun1.l.google.com:19302' },
    { urls: 'stun:stun2.l.google.com:19302' }
  ]
});
const stats = new Map();

pc.onicecandidate = (event) => {
  if (event.candidate === null) {
    console.table(Object.fromEntries(stats));
    return;
  }
  const key = event.url ?? 'ohne Server';
  stats.set(key, (stats.get(key) ?? 0) + 1);
};

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

{ 'ohne Server': 2, 'stun:stun1.l.google.com:19302': 1, 'stun:stun2.l.google.com:19302': 1 }

// Wichtig · Fallstricke

Veraltet: Die Spezifikation führt RTCPeerConnectionIceEvent.url nur noch aus Kompatibilitätsgründen. Verwenden Sie bevorzugt event.candidate.url.
Browser-Unterstützung: Chromium-Browser und Safari unterstützen die Eigenschaft, Firefox nicht (dort ist der Wert undefined). Schreiben Sie deshalb defensiv, z. B. event.candidate?.url ?? event.url ?? null.
Bei host-Kandidaten und beim abschließenden Ereignis (event.candidate === null) ist der Wert null. Ziehen Sie aus null also nicht den Schluss, dass ein Fehler vorliegt.
Wenn in einem iceServers-Eintrag mehrere URLs stehen, liefert die Eigenschaft genau die URL, die den Kandidaten erzeugt hat, nicht die ganze Liste.
Zugangsdaten für TURN (username, credential) erscheinen nie in url. Trotzdem gilt: TURN-Zugangsdaten sollten Sie nicht fest im Client-Code hinterlegen. Nutzen Sie stattdessen kurzlebige Zugangsdaten, die Ihr Server ausstellt.
Das Ereignis selbst gibt es nur in sicheren Kontexten (HTTPS oder localhost), in denen WebRTC verfügbar ist.

Siehe auch

RTCPeerConnectionIceEvent RTCPeerConnectionIceEvent.candidate RTCPeerConnection RTCIceCandidate.type PresentationConnectionAvailableEvent.connection