RTCPeerConnection.setConfiguration() — Methode · JavaScript-Referenz

Signatur

RTCPeerConnection.prototype.setConfiguration(configuration)

Beschreibung

Mit setConfiguration() änderst du die Einstellungen einer bereits erstellten RTCPeerConnection. Das Objekt hat denselben Aufbau wie das beim Konstruktor new RTCPeerConnection(configuration): iceServers, iceTransportPolicy, bundlePolicy, rtcpMuxPolicy, iceCandidatePoolSize und certificates.

Am häufigsten wird die Methode gebraucht, um kurzlebige TURN-Zugangsdaten zu erneuern, etwa zeitlich begrenzte Tokens nach dem TURN-REST-API-Muster. Ein zweiter Anwendungsfall: Scheitert eine direkte Verbindung, kannst du nachträglich auf iceTransportPolicy: "relay" umschalten, sodass nur noch Verbindungen über TURN-Server erlaubt sind.

Wichtig: Die Methode ersetzt die gesamte Konfiguration und ergänzt sie nicht. Am sichersten holst du dir die aktuelle Konfiguration mit getConfiguration(), änderst die gewünschten Felder und übergibst das Ergebnis wieder. Neue ICE-Server werden erst beim nächsten Sammeln von ICE-Kandidaten genutzt. Damit eine laufende Verbindung sie sofort verwendet, löst du danach mit restartIce() einen ICE-Neustart aus.

Parameter

Name	Typ	Default	Beschreibung
$configuration Pflicht	RTCConfiguration		Objekt mit den neuen Einstellungen. Die wichtigsten Felder: `iceServers` (Array aus `{ urls, username, credential }`), `iceTransportPolicy` (`"all"` \| `"relay"`), `bundlePolicy`, `rtcpMuxPolicy`, `iceCandidatePoolSize` und `certificates`. Nicht angegebene Felder fallen auf ihre Standardwerte zurück.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Bei ungültigen Werten wird synchron eine DOMException geworfen.

Beispiele

Abgelaufene TURN-Zugangsdaten erneuern

const pc = new RTCPeerConnection({
  iceServers: [{
    urls: 'turn:turn.example.com:3478',
    username: 'user-alt',
    credential: 'token-alt'
  }]
});

// Etwas später: neue, kurzlebige Zugangsdaten vom eigenen Server holen
const refreshTurnCredentials = async () => {
  const res = await fetch('/api/turn-credentials');
  const { username, credential } = await res.json();

  // Bestehende Konfiguration übernehmen und nur iceServers ersetzen
  const config = pc.getConfiguration();
  config.iceServers = [{
    urls: 'turn:turn.example.com:3478',
    username,
    credential
  }];
  pc.setConfiguration(config);
  console.log('TURN-Daten aktualisiert:', pc.getConfiguration().iceServers[0].username);
};

refreshTurnCredentials();

TURN-Daten aktualisiert: user-neu

Nach Verbindungsfehler auf reines TURN-Relay umschalten

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

pc.addEventListener('iceconnectionstatechange', () => {
  if (pc.iceConnectionState === 'failed') {
    pc.setConfiguration({
      ...pc.getConfiguration(),
      iceTransportPolicy: 'relay'
    });
    // ICE-Neustart, damit die neue Richtlinie sofort greift
    pc.restartIce();
    console.log('Umschalten auf Relay-Modus, ICE-Neustart ausgelöst');
  }
});

Umschalten auf Relay-Modus, ICE-Neustart ausgelöst

Fehler bei unzulässigen Änderungen abfangen

const pc = new RTCPeerConnection({ bundlePolicy: 'max-bundle' });

try {
  // bundlePolicy lässt sich nach der Erzeugung nicht mehr ändern
  pc.setConfiguration({ bundlePolicy: 'balanced' });
} catch (err) {
  console.log(err.name);
}

try {
  // TURN-Server ohne Zugangsdaten sind ungültig
  pc.setConfiguration({
    bundlePolicy: 'max-bundle',
    iceServers: [{ urls: 'turn:turn.example.com' }]
  });
} catch (err) {
  console.log(err.name);
}

InvalidModificationError InvalidAccessError

// Wichtig · Fallstricke

Die ganze Konfiguration wird ersetzt: Felder, die du weglässt, fallen auf ihre Standardwerte zurück. Weicht dabei z. B. bundlePolicy vom ursprünglichen Wert ab, wird ein Fehler geworfen. Deshalb am besten immer von getConfiguration() ausgehen.
Nicht änderbare Felder: bundlePolicy, rtcpMuxPolicy und certificates lassen sich nach der Erzeugung nicht mehr ändern. Ein Versuch führt zu InvalidModificationError. Dasselbe gilt für iceCandidatePoolSize, sobald setLocalDescription() aufgerufen wurde.
Weitere Ausnahmen: InvalidStateError, wenn die Verbindung schon geschlossen ist. SyntaxError bei ungültigen ICE-Server-URLs. InvalidAccessError, wenn bei einem turn:- oder turns:-Server username oder credential fehlt. NotSupportedError bei nicht unterstützten URL-Schemata.
Keine sofortige Wirkung auf laufende Verbindungen: Neue ICE-Server werden erst beim nächsten Sammeln von Kandidaten genutzt. Mit restartIce() erzwingst du das.
Sicherheit: TURN-Zugangsdaten sind im Client immer sichtbar. Nutze darum kurzlebige, serverseitig erzeugte Zugangsdaten statt fester Passwörter im Quellcode.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt. Ältere Safari-Versionen bis ca. 12 hatten Probleme beim Ändern von iceServers, daher auf Zielplattformen testen.

Siehe auch

RTCPeerConnection RTCPeerConnection.getConfiguration() RTCPeerConnection.restartIce() RTCPeerConnection.setLocalDescription() new RTCPeerConnectionIceEvent()