RTCIceCandidate.type — Eigenschaft · JavaScript-Referenz

Signatur

RTCIceCandidate.type

Beschreibung

Die Eigenschaft type eines RTCIceCandidate-Objekts sagt, auf welchem Weg die Netzwerkadresse des Kandidaten gefunden wurde. Der Wert kommt aus dem Feld typ in der SDP-Zeile candidate (a=candidate:… typ srflx …) und ist ein Wert des Aufzählungstyps RTCIceCandidateType.

"host": Die echte IP-Adresse eines lokalen Netzwerkadapters oder eine mDNS-Adresse wie xyz.local.
"srflx" (server reflexive): Die öffentliche Adresse, die ein STUN-Server von außen hinter einem NAT sieht.
"prflx" (peer reflexive): Eine Adresse, die erst bei den Verbindungsprüfungen mit der Gegenstelle entdeckt wurde.
"relay": Eine Adresse auf einem TURN-Server, der den Datenverkehr weiterleitet.

In der Praxis braucht man type vor allem zur Fehlersuche bei der Verbindung: Man prüft, ob STUN/TURN richtig eingerichtet sind, filtert Kandidaten (z. B. nur Relay für mehr Privatsphäre) oder erfasst, welche Verbindungsart später tatsächlich genutzt wird. Wenn keine srflx- oder relay-Kandidaten auftauchen, stimmt meist die ICE-Server-Konfiguration nicht.

Rückgabewert

Typ

"host" | "srflx" | "prflx" | "relay" | null

Beschreibung

Ein RTCIceCandidateType-String. null, wenn der Kandidat keinen gültigen Typ hat, z. B. bei einem leeren Kandidaten, der das Ende der Kandidatensuche signalisiert.

Beispiele

Gesammelte Kandidaten nach Typ protokollieren

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

pc.addEventListener('icecandidate', ({ candidate }) => {
  if (!candidate) {
    console.log('Kandidatensuche abgeschlossen');
    return;
  }
  console.log(`${candidate.type}: ${candidate.address}:${candidate.port} (${candidate.protocol})`);
});

// Ein DataChannel stößt die Kandidatensuche an
pc.createDataChannel('test');
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

host: 3f1c…-uuid.local:54321 (udp) srflx: 203.0.113.17:54321 (udp) Kandidatensuche abgeschlossen

TURN-Server-Konfiguration prüfen

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

  pc.onicecandidate = ({ candidate }) => {
    if (candidate?.type === 'relay') {
      clearTimeout(timer);
      pc.close();
      resolve(true);
    }
  };
  pc.createDataChannel('probe');
  pc.createOffer().then((o) => pc.setLocalDescription(o));
});

const ok = await testTurn({
  urls: 'turn:turn.example.com:3478',
  username: 'user',
  credential: 'secret'
});
console.log(ok ? 'TURN funktioniert' : 'Kein Relay-Kandidat erhalten');

TURN funktioniert

Nur Relay-Kandidaten an die Gegenstelle senden

const signaling = new WebSocket('wss://signal.example.com');
const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'turn:turn.example.com:3478', username: 'u', credential: 'p' }]
});

pc.onicecandidate = ({ candidate }) => {
  // Host- und srflx-Kandidaten verwerfen, um die eigene IP zu verbergen
  if (candidate && candidate.type !== 'relay') return;
  signaling.send(JSON.stringify({ candidate }));
};

// Wichtig · Fallstricke

Privatsphäre: host-Kandidaten enthalten in modernen Browsern meist eine mDNS-Adresse (*.local) statt der echten lokalen IP. Wer IP-Lecks sicher vermeiden will, setzt besser iceTransportPolicy: "relay" in der RTCPeerConnection-Konfiguration, statt die Kandidaten selbst zu filtern.
prflx-Kandidaten treten nicht im icecandidate-Event auf. Sie entstehen erst während der Verbindungsprüfung und sind nur über getStats() (candidateType in local-candidate/remote-candidate) zu sehen.
Der Kandidat mit candidate === null bzw. einem leeren candidate-String zeigt das Ende der Kandidatensuche an. Dann ist type null, also vorher prüfen, etwa mit optionaler Verkettung (?.).
Welcher Kandidat tatsächlich genutzt wird, verrät type allein nicht. Dafür braucht man das ausgewählte Kandidatenpaar in getStats() bzw. RTCIceTransport.getSelectedCandidatePair().
Kompatibilität: Chrome, Edge und Safari unterstützen die Eigenschaft seit Langem, Firefox erst seit Version 112. In älteren Umgebungen muss man typ selbst aus candidate.candidate auslesen.

Siehe auch

RTCIceCandidate RTCIceCandidate.candidate RTCIceCandidate.address RTCIceCandidate.protocol RTCPeerConnection.getStats() RTCIceCandidateStats.type