RTCPeerConnection.restartIce()

The WebRTC API's RTCPeerConnection interface offers the restartIce() method to allow a web application to easily request that ICE candidate gathering be redone on both ends of the connection. This simplifies the process by allowing the same method to be used by either the caller or the receiver to trigger an ICE restart.

After restartIce() returns, the offer returned by the next call to createOffer() is automatically configured to trigger ICE restart on both the local peer (once the local peer has been set) and on the remote peer, once the offer is sent across your signaling mechanism and the remote peer has set its description as well.

restartIce() causes the negotiationneeded event to be fired on the RTCPeerConnection to inform the application that it should perform negotiation using its signaling channel.

If negotiation fails to complete—either due to rollback or because incoming offers are in the process of being negotiated—the RTCPeerConnection will remember that you requested ICE restart. The next time the connection's signalingState changes to stable, the connection will fire the negotiationneeded event. This process continues until an ICE restart has been successfully completed.

Syntax

rtcPeerConnection.restartIce();

Parameters

None.

Return value

undefined.

Usage notes

After calling restartIce(), the next offer created using createOffer() will initiate ICE restart once sent to the remote peer over your signaling mechanism. Restarting ICE essentially resets ICE so that it creates all new candidates using new credentials. Existing media transmissions continue uninterrupted during this process.

For details about how ICE restart works, see ICE restart in Lifetime of a WebRTC session and RFC 5245, section 9.1.1.1: ICE specification.

Example

This example creates a handler for the iceconnectionstatechange event that handles a transition to the failed state by restarting ICE in order to try again.

pc.addEventListener("iceconnectionstatechange", event => {
  if (pc.iceConnectionState === "failed") {
    /* possibly reconfigure the connection in some way here */
    /* then request ICE restart */
    pc.restartIce();
  }
});

With this code in place, a transition to the failed state during ICE negotiation will cause a negotiationneeded event to be fired, in response to which your code should renegotiate as usual. However, because you have called restartIce(), your call to createOffer() which occurs in the handler for negotiationneeded will trigger an ICE restart rather than just a regular renegotiation.

Specifications

Specification Status Comment
WebRTC 1.0: Real-time Communication Between Browsers
The definition of 'RTCPeerConnection.restartIce()' in that specification.
Candidate Recommendation Initial definition.

Browser compatibility

DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
restartIce() methodChrome Full support 77Edge Full support 79Firefox Full support 70IE No support NoOpera No support NoSafari No support NoWebView Android Full support 77Chrome Android Full support 77Firefox Android No support NoOpera Android Full support 55Safari iOS No support NoSamsung Internet Android Full support 12.0

Legend

Full support
Full support
No support
No support

See also