RTCOfferOptions.iceRestart

The iceRestart property of the RTCOfferOptions dictionary is a Boolean value which, when true, tells the RTCPeerConnection to start ICE renegotiation.

Note: Rather than manually creating and submitting an offer with iceRestart set to true, you should consider calling the RTCPeerConnection method restartIce() instead.

Syntax

var options = {
  iceRestart: trueOrFalse
};

Value

A Boolean value indicating whether or not the RTCPeerConnection should generate new values for the connection's ice-ufrag and ice-pwd values, which will trigger ICE renegotiation on the next message sent to the remote peer.

Usage notes

When the RTCPeerConnection object's ICE connection state changes to failed, you should try to trigger an ICE restart. You should ideally do this by calling the RTCPeerConnection's restartIce() method, if it's available.

Fundamentally, this renegotiation is triggered by generating and using new values for the ICE username fragment ("ufrag")}}

Example

This example shows a handler for the iceconnectionstatechange event. It watches for the ICE connection state to transition to "failed", which indicates that an ICE restart should be tried in order to attempt to bring the connection back up.

pc.oniceconnectionstatechange = function(evt) {
  if (pc.iceConnectionState === "failed") {
    if (pc.restartIce) {
      pc.restartIce();
    } else {
      pc.createOffer({ iceRestart: true })
      .then(pc.setLocalDescription)
      .then(sendOfferToServer);
    }
  }
}

If the state changes to failed, this handler starts by looking to see if the RTCPeerConnection includes the restartIce() method; if it does, we call that to request an ICE restart. Otherwise, we call back to the older technique: we manually create a new offer with iceRestart set to true, then that offer is set as the new local description for the connection. After that, the offer is sent to the server by calling a custom function sendOfferToServer().

Specifications

Specification Status Comment
WebRTC 1.0: Real-time Communication Between Browsers
The definition of 'RTCOfferOptions.iceRestart' in that specification.
Candidate Recommendation Initial definition.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
iceRestartChrome Full support 50Edge Full support ≤79Firefox Full support 48IE No support NoOpera ? Safari ? WebView Android Full support 50Chrome Android Full support 50Firefox Android Full support 48Opera Android ? Safari iOS ? Samsung Internet Android Full support 5.0

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown