Getting started with the Browser SDK
The Whereby Browser SDK lets you add video calling to your web application, customizing layout and features to fit your use case and brand.
Last updated
Was this helpful?
The Whereby Browser SDK lets you add video calling to your web application, customizing layout and features to fit your use case and brand.
Last updated
Was this helpful?
The Whereby Browser SDK takes advantage of React. This tutorial assumes that you're familiar with JavaScript, React and its JSX syntax. You should also be familiar with either or , JavaScript's primary package managers.
To follow along with this tutorial, you'll need to do two things.
Sign up for a account. You can get started with Whereby's free plan. It provides you with 2,000 participant minutes each month.
Create a Whereby meeting room. You'll need the meeting room's URL. Create your room using the wizard on your account dashboard or with Whereby's . For this tutorial, leave the room unlocked.
You should also have a basic React project set up. or will get you up-and-running quickly.
First, add the Whereby Browser SDK to your React project. We'll need to install version 2.0.0-beta3 or later. Open a terminal window and type (or copy-and-paste) the following command.
Next, connect to your room. The Whereby Browser SDK exposes a custom React hook — — that connects participants in a meeting room. Import both React and useRoomConnection into your project file as shown below.
The useRoomConnection hook requires two parameters:
A Whereby room URL
An object that contains a localMediaOptions field. localMediaOptions determines whether the browser should request access to a participant's camera, microphone, or both.
Use the useRoomConnection hook inside of a component function.
state, an object that reflects the status of the current room, including the call's participants;
components, an object containing the pre-bound components available in the room; and
actions, an object representing the available actions in the room.
This tutorial will introduce you to all three in more detail later, but first we need to join the room.
The actions object contains joinRoom and leaveRoom functions.
joinRoom does what it says on the tin, it tells the SDK to join the provided room. You can attach this to a button if you like, but for now we'll add a simple useEffect hook to join the room as soon as the component is rendered.
We also provide a cleanup function to useEffect that will leave the room if the component is unmounted.
localParticipant, an object that represents the individual meeting attendee (you, in this case); and
remoteParticipants, an array of objects representing other meeting participants.
Each localParticipant and remoteParticipants object contains a stream property, that you'll use with the VideoView component to display video for each participant.
VideoView requires a stream prop. Set its value to localParticipant.stream. The muted prop is optional, but good to use when rendering VideoView. Using muted for the localParticipant view prevents audio feedback from your own microphone.
In the preceding example, the camera and microphone are enabled for the local participant — that's you. You probably want the ability to turn your camera and microphone off and on, though. You can accomplish that using the toggleCamera and toggleMicrophone methods of the actions property.
Then update your markup to add a button for each control.
In the click handler for each button, you'll first need to update state for your camera (setIsCameraActive) or microphone (setIsMicrophoneActive), before invoking the appropriate toggle method. Each meeting participant will have these controls available in their meeting room view.
As with localParticipant, each remoteParticipant object contains a stream property. Set remoteParticipant.stream as the value of the stream prop for each VideoView instance. Don’t add the muted property to the VideoView component here. Doing so would mute audio for all attendees in the room.
Altogether, your code should now resemble the example below.
From here, you're ready to add CSS to change your meeting layout. Or, you can replace the default browser buttons with custom icon components.
Whereby rooms can be locked, allowing room hosts to control who enters a room.
The actions object has a knock function that we can use to let the host know we'd like to join their room.
When the room state.connectionStatus is room_locked, we can render a button to knock, and the connectionState will update to knocking until the host lets us in. A simple implementation of this might look like this:
useRoomConnection returns a object that contains three properties:
includes two properties that represent participants in the meeting:
To see your own video stream, use the localParticipant property. Check whether localParticipant has an active stream, then conditionally render the component as shown below.
Note: The examples in this tutorial use , a syntax that allows you to extract Object properties into variables.
If you prefer, you can use (e.g. connection.components.VideoView or connection.state.localParticipant) to access these values.
Any attribute supported by HTML's can be added as a VideoView prop. Remember, however, to use className instead of class when adding CSS class names to React components.
Set an initial state for the camera and microphone with .
Talking to yourself is normal, but it's not a video call until you're talking to someone else. Use the remoteParticipants property and to display the other participants' video streams.
Whereby's Browser SDK is a truly . It decouples the video stream from the standard Whereby UI so that you can create rich video conferencing, , or experiences that reflect you or your brand.
Written by