RTCIceCandidate.toJSON() — Methode · JavaScript-Referenz

Signatur

RTCIceCandidate.prototype.toJSON()

Beschreibung

Die Methode toJSON() erzeugt aus einem RTCIceCandidate ein einfaches Objekt (Dictionary vom Typ RTCIceCandidateInit). Es enthält die Eigenschaften candidate, sdpMid, sdpMLineIndex und usernameFragment. Einen JSON-String liefert sie nicht. Das Objekt lässt sich aber direkt mit JSON.stringify() serialisieren.

Gebraucht wird die Methode vor allem beim Signaling in WebRTC: ICE-Kandidaten aus dem Ereignis icecandidate müssen über einen eigenen Kanal (WebSocket, HTTP, Server-Sent Events …) an die Gegenstelle gehen. Weil JSON.stringify() toJSON() automatisch aufruft, kann man den Kandidaten meist direkt übergeben.

Auf der Empfängerseite übergibt man das empfangene Objekt an new RTCIceCandidate(init) oder direkt an RTCPeerConnection.addIceCandidate(). Das Objekt ist genau so aufgebaut, wie diese Aufrufe es erwarten.

Rückgabewert

Typ

RTCIceCandidateInit

Beschreibung

Ein einfaches Objekt mit den Eigenschaften candidate (string), sdpMid (string | null), sdpMLineIndex (number | null) und usernameFragment (string | null).

Beispiele

Kandidaten in ein Objekt umwandeln

const candidate = new RTCIceCandidate({
  candidate: 'candidate:842163049 1 udp 1677729535 203.0.113.5 50000 typ srflx raddr 0.0.0.0 rport 0 generation 0',
  sdpMid: '0',
  sdpMLineIndex: 0
});

const init = candidate.toJSON();
console.log(typeof init, init.sdpMid, init.sdpMLineIndex);

object 0 0

ICE-Kandidaten per WebSocket an die Gegenstelle senden

const socket = new WebSocket('wss://signaling.example.com');
const pc = new RTCPeerConnection({ iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] });

pc.addEventListener('icecandidate', ({ candidate }) => {
  if (!candidate) return; // Kandidatensuche abgeschlossen
  // JSON.stringify ruft toJSON() automatisch auf
  socket.send(JSON.stringify({ type: 'candidate', payload: candidate.toJSON() }));
});

Empfangenen Kandidaten wieder hinzufügen

const pc = new RTCPeerConnection();

const handleMessage = async (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type !== 'candidate') return;
  try {
    await pc.addIceCandidate(new RTCIceCandidate(msg.payload));
    console.log('Kandidat hinzugefügt');
  } catch (err) {
    console.error('Fehler beim Hinzufügen:', err);
  }
};

// socket.addEventListener('message', handleMessage);

Kandidat hinzugefügt

// Wichtig · Fallstricke

toJSON() gibt ein Objekt zurück, keinen String. Zum Übertragen brauchen Sie weiterhin JSON.stringify().
Nur die vier Init-Felder werden übernommen. Abgeleitete Eigenschaften wie address, port, protocol, type oder priority fehlen im Ergebnis. Die Gegenstelle liest sie beim Aufbau aus dem candidate-String neu aus.
Das Ereignis icecandidate liefert am Ende candidate === null. Rufen Sie toJSON() dann nicht auf, sonst gibt es einen TypeError.
Ältere Browser setzen usernameFragment teils nicht. In Safari vor Version 11 fehlt die Methode ganz.
Datenschutz: Kandidaten können lokale oder öffentliche IP-Adressen enthalten. Übertragen Sie sie nur über einen gesicherten Signaling-Kanal (wss://).

Siehe auch

RTCIceCandidate RTCPeerConnection.prototype.addIceCandidate() JSON.stringify() AudioPlaybackStats.toJSON() PerformancePaintTiming.toJSON()