RTCPeerConnection.onnegotiationneeded

The RTCPeerConnection interface's onnegotiationneeded property is an EventListener which specifies a function which is called to handle the negotiationneeded event when it occurs on an RTCPeerConnection instance. This event is fired when a change has occurred which requires session negotiation. This negotiation should be carried out as the offerer, because some session changes cannot be negotiated as the answerer.

Most commonly, the negotiationneeded event is fired after a send track is added to the RTCPeerConnection. If the session is modified in a manner that requires negotiation while a negotiation is already in progress, no negotiationneeded event will fire until negotiation completes, and only then if negotiation is still needed.

Syntax

RTCPeerConnection.onnegotiationneeded = eventHandler;

Value

This should be set to a function you provide which is passed a single parameter: an Event object containing the negotiationneeded event. There's no additional information provided in the event; anything you need, you can get by examining the properties of the RTCPeerConnection.

Example

This example, derived from the example in Signaling and video calling, establishes a handler for negotiationneeded events to handle creating an offer, configuring the local end of the connection, and sending the offer to the remote peer.

pc.onnegotiationneeded = function() {
  pc.createOffer().then(function(offer) {
    return pc.setLocalDescription(offer);
  })
  .then(function() {
      // Send the offer to the remote peer through the signaling server
    });
  })
  .catch(reportError);
}

First, it creates the offer by calling createOffer(). When that succeeds, the offer is passed into setLocalDescription() to set the local description for the connection. Once that's succeeded in turn, the offer can be sent to the signaling server for delivery to the remote peer.

Specifications

Browser compatibility

See also

• The negotiationneeded event and its type, Event.