Signatur
Beschreibung
restartIce() startet einen ICE-Neustart (Interactive Connectivity Establishment). Die Methode baut die Verbindung nicht selbst neu auf. Sie markiert die RTCPeerConnection so, dass das nächste mit createOffer() erzeugte Angebot neue ICE-Zugangsdaten (ice-ufrag/ice-pwd) enthält. Nachdem dieses Angebot über den Signalisierungskanal ausgetauscht wurde, sammeln beide Seiten neue Kandidaten und suchen einen neuen Netzwerkpfad. Die laufenden Medienströme bleiben dabei bestehen.
Typische Anwendungsfälle sind ein Wechsel des Netzwerks (z. B. von WLAN zu Mobilfunk), ein Verbindungsabbruch mit iceConnectionState === "failed" oder geänderte TURN-Server-Einstellungen über setConfiguration(). Meist ruft man die Methode in einem Handler für iceconnectionstatechange bzw. connectionstatechange auf.
Nach dem Aufruf wird das Ereignis negotiationneeded ausgelöst. Wenn die Anwendung „Perfect Negotiation“ mit einem onnegotiationneeded-Handler umsetzt, läuft der Neustart automatisch: Der Handler ruft setLocalDescription() ohne Argumente auf, erzeugt so ein Angebot mit ICE-Neustart und sendet es an die Gegenseite. Ist gerade eine Aushandlung im Gange, merkt sich der Browser den Neustart für die nächste Aushandlung vor.
Rückgabewert
undefined). Der Neustart läuft asynchron über das Ereignis negotiationneeded und die folgende Angebot/Antwort-Aushandlung.Beispiele
ICE-Neustart bei fehlgeschlagener Verbindung
const pc = new RTCPeerConnection({
iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
});
pc.addEventListener('iceconnectionstatechange', () => {
console.log('ICE-Status:', pc.iceConnectionState);
if (pc.iceConnectionState === 'failed') {
// Neue Kandidaten anfordern; löst negotiationneeded aus
pc.restartIce();
}
});Zusammenspiel mit Perfect Negotiation
// signaling: z. B. ein WebSocket-Wrapper mit send()
const pc = new RTCPeerConnection();
pc.onnegotiationneeded = async () => {
try {
// Ohne Argument: Browser erzeugt passendes Angebot, inkl. ICE-Neustart
await pc.setLocalDescription();
signaling.send({ description: pc.localDescription });
} catch (err) {
console.error('Aushandlung fehlgeschlagen:', err);
}
};
pc.onicecandidate = ({ candidate }) => {
if (candidate) signaling.send({ candidate });
};
pc.onconnectionstatechange = () => {
if (pc.connectionState === 'failed') {
pc.restartIce();
}
};Neustart nach Netzwerkwechsel mit neuen TURN-Servern
const reconnectWithNewTurn = async (pc) => {
// Frische, kurzlebige TURN-Zugangsdaten vom eigenen Server holen
const res = await fetch('/api/turn-credentials');
const { urls, username, credential } = await res.json();
pc.setConfiguration({
...pc.getConfiguration(),
iceServers: [{ urls, username, credential }]
});
pc.restartIce();
console.log('ICE-Neustart angefordert');
};
window.addEventListener('online', () => reconnectWithNewTurn(pc));// Wichtig · Fallstricke
- Keine eigene Signalisierung:
restartIce()ändert nur den internen Zustand. Ohnenegotiationneeded-Handler bzw. ohne manuellescreateOffer()mit anschließendem Versand an die Gegenseite passiert nichts. - Veraltete Alternative: Früher erzwang man den Neustart mit
createOffer({ iceRestart: true }). Das funktioniert weiterhin,restartIce()ist aber der empfohlene Weg, weil es auch bei laufender Aushandlung zuverlässig greift. - Geschlossene Verbindung: Ist
signalingStategleich"closed", hat der Aufruf keine Wirkung. - Status „disconnected“: Dieser Zustand ist oft nur vorübergehend. Wartet vor einem Neustart kurz ab (z. B. einige Sekunden), damit ihr keine unnötigen Neuaushandlungen auslöst.
- Browser-Kompatibilität: Unterstützt ab Chrome/Edge 77, Firefox 70 und Safari 14.1. In älteren Browsern auf
createOffer({ iceRestart: true })ausweichen, z. B. nach Prüfung mit'restartIce' in RTCPeerConnection.prototype. - Nur in sicheren Kontexten (HTTPS) sinnvoll nutzbar, weil Medienzugriff und WebRTC dort meist vorausgesetzt werden.