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.
What you'll need
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 npm or yarn, JavaScript's primary package managers.
To follow along with this tutorial, you'll need to do two things.
Sign up for a Whereby Embedded 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 REST API. For this tutorial, leave the room unlocked.
You should also have a basic React project set up. Vite or Parcel will get you up-and-running quickly.
Install the SDK
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.
If you're using yarn as your package manager, replace npm i
with yarn
add (e.g. yarn add @whereby.com/browser-sdk
).
Connecting to your room
Next, connect to your room. The Whereby Browser SDK exposes a custom React hook — useRoomConnection
— 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.
useRoomConnection
returns a RoomConnectionReference
object that contains three properties:
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; andactions
, an object representing the available actions in the room.
This tutorial will introduce you to all three.
See yourself on screen
RoomConnectionReference.state
includes two properties that represent participants in the meeting:
localParticipant
, an object that represents the individual meeting attendee (you, in this case); andremoteParticipants
, 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.
To see your own video stream, use the localParticipant
property. Check whether localParticipant
has an active stream, then conditionally render the VideoView
component as shown below.
Note: The examples in this tutorial use destructuring assignment, a syntax that allows you to extract Object properties into variables.
If you prefer, you can use dot-syntax (e.g. connection.components.VideoView or connection.state.localParticipant) to access these values.
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.
Any attribute supported by HTML's <video> element can be added as a VideoView
prop. Remember, however, to use className
instead of class
when adding CSS class names to React components.
Add microphone and camera controls
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.
Set an initial state for the camera and microphone with React.useState()
.
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.
Add friends and colleagues
Talking to yourself is normal, but it's not a video call until you're talking to someone else. Use the remoteParticipants
property and Array.prototype.map()
to display the other participants' video streams.
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's Browser SDK is a truly "white-label" solution for video calling. It decouples the video stream from the standard Whereby UI so that you can create rich video conferencing, virtual classrooms, or telehealth experiences that reflect you or your brand.
Written by Tiffany Brown
Last updated