openvidu-webcomponent 🔗

Check it on GitHub

OpenVidu Web Component is the simplest and quickest way to add videoconference capabilities to your existing web application. It brings many of the features of OpenVidu platform, making it very powerful. With just a few lines of code you will have your first video call working!

Running this tutorial 🔗



1) Clone the repo:

git clone https://github.com/OpenVidu/openvidu-tutorials.git -b v2.22.0

2) You will need an http web server installed in your development computer to execute the tutorial. If you have node.js installed, you can use http-server to serve application files. It can be installed with:

npm install -g http-server

3) Run the tutorial:

http-server openvidu-tutorials/openvidu-webcomponent/web

4) OpenVidu Server must be up and running in your development machine. The easiest way is running this Docker container which wraps both of them (you will need Docker CE):

# WARNING: this container is not suitable for production deployments of OpenVidu Platform
# Visit https://docs.openvidu.io/en/stable/deployment

docker run -p 4443:4443 --rm -e OPENVIDU_SECRET=MY_SECRET openvidu/openvidu-server-kms:2.22.0

5) Go to http://localhost:8080 to test the app once the server is running. The first time you use the docker container, an alert message will suggest you accept the self-signed certificate of openvidu-server when you first try to join a session.

If you are using Windows, read this FAQ to properly run the tutorial

To learn some tips to develop with OpenVidu, check this FAQ

Understanding the code 🔗

This application is very simple. It has only 4 files:

  • openvidu-webcomponent-{VERSION}.js: JavaScript file of OpenVidu Web Component. You don't have to manipulate this file.
  • openvidu-webcomponent-{VERSION}.css: styles for OpenVidu Web Component. You don't have to manipulate this file.
  • app.js: sample application main JavaScript file.
  • index.html: HTML code of the application.

Let's see how OpenVidu Web Component works:


index.html 🔗

Inside of the head section of index.html, we reference our app.js script and openvidu-webcomponent files:

<head>

    <!--... other imports ...-->

    <script src="app.js"></script>
    <script src='openvidu-webcomponent-{VERSION}.js'></script>
    <link rel="stylesheet" href="openvidu-webcomponent-{VERSION}.css">
</head>

As you can see, the index.html body has the form to connect to a video-session and the OpenVidu Web Component, which starts hidden:

<body>

    <!-- Form to connect to a video-session -->
    <div id="main" style="text-align: center;">
        <h1>Join a video session</h1>
        <form onsubmit="joinSession(); return false" style="padding: 80px; margin: auto">
            <p>
                <label>Session:</label>
                <input type="text" id="sessionName" value="SessionA" required>
            </p>
            <p>
                <label>User:</label>
                <input type="text" id="user" value="User1" required>
            </p>
            <p>
                <input type="submit" value="JOIN">
            </p>
        </form>
    </div>

    <!-- OpenVidu Web Component -->
    <openvidu-webcomponent style="display: none;"></openvidu-webcomponent>

</body>

In this tutorial, we just alternate the view between the form and the web component, hiding or showing them depending on the Web Component events received. See next point for checking the details.


app.js (I): OpenVidu Web Component events 🔗

The OpenVidu Web Component offers several events you can handle them in our JavaScript code. As the OpenVidu Web Component is created from the openvidu-angular library, you can see all events here.

We just need to get the element once the document is ready and add all the listeners we want:

$(document).ready(() => {
    var webComponent = document.querySelector('openvidu-webcomponent');

    webComponent.addEventListener('onSessionCreated', (event) => {
         var session = event.detail;
     });
    webComponent.addEventListener('onJoinButtonClicked', (event) => {});
    webComponent.addEventListener('onToolbarLeaveButtonClicked', (event) => {});
    webComponent.addEventListener('onToolbarCameraButtonClicked', (event) => {});
    webComponent.addEventListener('onToolbarMicrophoneButtonClicked', (event) => {});
    webComponent.addEventListener('onToolbarScreenshareButtonClicked', (event) => {});
    webComponent.addEventListener('onToolbarParticipantsPanelButtonClicked', (event) => {});
    webComponent.addEventListener('onToolbarChatPanelButtonClicked', (event) => {});
    webComponent.addEventListener('onToolbarFullscreenButtonClicked', (event) => {});
    webComponent.addEventListener('onParticipantCreated', (event) => {});
});

We should mention that the onSessionCreated is returning the openvidu-browser Session object so we will be able to use session in the same way as if we used openvidu-browser directly, and of course use openvidu-browser API.


app.js (II): Configuring OpenVidu Web Component 🔗

The joinSession method is invoked after clicking on the our webapp join button. The main logic that it handles is the following:

  • Get the form input values, with the videoconference to connect and the nickname the user will have in it.
  • Get the two tokens from OpenVidu Server. Check out next point to see how this is done.

The tokens are the only parameter that the webcomponent needs. Once we have our tokens ready, we set them to the webcomponent.

We also have assigned a participantName for displaying our name in the videoconference. In addition, there are several optional parameters that we can set up for customizing the UI. Check them here.

async function joinSession() {
    //Getting form inputvalue
    var sessionName = document.getElementById('sessionName').value;
    var participantName = document.getElementById('user').value;

    // Requesting tokens
    var tokens = {webcam: await getToken(sessionName), screen: await getToken(sessionName)};

    //Getting the webcomponent element
    var webComponent = document.querySelector('openvidu-webcomponent');

    hideForm();

    // Displaying webcomponent
    webComponent.style.display = 'block';

    // Setting up our name and tokens
    webComponent.participantName = participantName;
    webComponent.tokens = tokens;
}

That's it. Once you configure the tokens into the webcomponent, it will automatically join the proper session (onSessionCreated event will be dispatched so you can update your webapp).

You will be able to see the videconference working and every participant who connects to the same session will be displayed on it.


Get a token from OpenVidu Server 🔗

WARNING: This makes this tutorial an insecure application. We need to ask OpenVidu Server for a user token in order to connect to our session. This process should entirely take place in our server-side, not in our client-side. But due to the lack of an application backend in this tutorial, the JavaScript code itself will perform the POST operations to OpenVidu Server

The token must has inside of an array. If you want that the app allows the screen sharing you must include two differents tokens in the array. If you only add one, the app doesn't allow the screen sharing funcionality.

getToken(sessionName).then((token) => {
    // Send the 'token' to OpenVidu web component
});

In a production environment we would perform this operations in our application backend, by making use of the REST API, OpenVidu Java Client or OpenVidu Node Client. Here we have implemented the POST requests to OpenVidu Server in a method getToken() that returns a Promise with the token. Without going into too much detail, this method performs two ajax requests to OpenVidu Server, passing OpenVidu Server secret to authenticate them:

  • First ajax request performs a POST to /openvidu/api/sessions (we send a customSessionId field to name the session with our sessionName value retrieved from HTML input)
  • Second ajax request performs a POST to /openvidu/api/sessions/<sessionId>/connection (the path requires the sessionId to assign the token to this same session)

You can inspect this method in detail in the GitHub repo.


Close the session dynamically 🔗

You can also disconnect the user from the session dynamically calling to disconnect method which the OpenVidu Webcomponent provides:

webComponent.disconnect();

OpenVidu Web Component Customization 🔗

UI Customization 🔗

In the tutorial above, OpenVidu Web Component receives the participantName parameter dynamically like this:

webComponent.participantName = participantName;

In addition to this parameter, OpenVidu Web Component offers several other parameters for customizing the UI as you wish. You can see all the UI parameters here.

Here are some examples:

// Hide the prejoin page
webComponent.prejoin = false;

// Hide the fullscreen button
webComponent.toolbarFullscreenButton = false;

// Hide the branding logo
webComponent.toolbarDisplayLogo = false;

You can also set them statically, for example if you are building your template in the backend:

WARNING: As you can see, when you add parameters to OpenVidu Web Component statically, you have to replace the camelCase with a hyphen between words.
<openvidu-webcomponent
    tokens="TOKEN_RETRIEVED_FROM_OPENVIDU_SERVER"
    prejoin="false"
    toolbar-fullscreen-button="false"
    toolbar-display-logo="false"
    >
</openvidu-webcomponent>

Styles Customization 🔗

The OpenVidu Web Component also allows you to customize the styles to your liking.

You can update the css styles which you can find here.

:root {
  --ov-primary-color: #303030;
  --ov-secondary-color: #3e3f3f;
  --ov-tertiary-color: #598eff;
  --ov-warn-color: #EB5144;
  --ov-accent-color: #ffae35;
  --ov-light-color: #e6e6e6;

  --ov-logo-background-color: #3e3f3f;
  --ov-text-color: #ffffff;

  --ov-panel-text-color: #1d1d1d;
  --ov-panel-background: #ffffff;

  --ov-buttons-radius: 50%;
  --ov-leave-button-radius: 10px;
  --ov-video-radius: 5px;
  --ov-panel-radius: 5px;
}

With OpenVidu Web Component you will also be able to replace the OpenVidu branding logo with yours. You only have to go to web/assets/images/ and add your custom logo file with the logo.png name.