use-webrtc-connection

The useWebRTCConnection hook provides the logic to create WebRTC connections and ICE candidates for the corresponding peer connection. It takes care of the async processes in the background and translates them to usable react state.

import useWebRTCConnection from "@formoe/use-webrtc-connection"

…

const { openConnection, rtcPeerConnection, addIceCandidate, addIceCandidateErrors, closeConnection } = useWebRTCConnection({ onIceCandidate, connectionConfig })

Hook configuration

The hook takes a configuration object taking a mandatory onIceCandidate callback function that is triggered if the connection provides new candidates. This is mandatory, as it would not make sense to open a connection without ultimately reacting to candidates. As candidates are only send to the peer most of the times the hook does not provide them as state.

connectionConfig is a RTCConfiguration object used when creating a new RTCPeerConnection. You can defined define ice servers here for example.

Returned WebRTC interface

The hook returns some objects and various functions to control the connection process.

The connection

To open a connection you can:

openConnection()

useEffect(() => {
  // open for business
}, [rtcPeerConnection])

The rtcPeerConnection returned by the hook is a RTCPeerConnection object or undefined if no connection was opened. It can also be used to further interact with the connection in case the direct interface is not sufficient.

Evaluating candidates

Sending a candidate

To sucessfully establish a peer connection, the WebRTC layer needs to exchange candidates between the peers.

The callback handed in to the hook via the configuration object is triggered whenever a new RTCIceCandidate is avaialable for the connection:

const onIceCandidate = (candidate) => {
  // signal the peer
}

At this point you don't need to do anything other than sending the candidate to the peer connection. Everything else is taken care of by the WebRTC layer.

Receiving a candidate

If you however retreive a new candidate from your peer, you need to make it know to the connection. The hook makes use of the @formoe/use-multi-async package to deal with this:

const candidateId = addIceCandidate(newCandidate)

addIceCandidate takes a RTCIceCandidate and starts the async process of adding it to the connection. It also returns a Symbol for the candidate. If anything goes wrong with setting it, you can find the correspondng error in the addIceCandidateErrors Array provided by the hook. The entries of the array have the id of their corresponding addIceCandidate call and the error as a JS Error object.

const error = addIceCandidateErrors.find(({id}) => id === candidateId)

if (error) {
  // You might want to notify the user somehow or react to the error.
}

Keep in mind though, that it is not necessarily critical if errors occur. WebRTC negotiation is a constant process throughout the connection and even if adding some candidates results in errors, others might be valid and establish a connection.

The hook keeps only the last 20 errors available.

Hanging up

To manually close an established connection just call:

closeConnection()